Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / cwl2f-3.zip / MANUAL.DOC < prev next >

Wrap

Text File | 1992-04-26 | 709KB | 21,707 lines

@ME.FORMAT R THE C WINDOW LIBRARY (c) Copyright P. A. McKenzie 1990, 1991, 1992 All Rights Reserved Version 2.0e T A B L E O F C O N T E N T S PRELIMINARIES ......................................... i Microsoft C ........................................ i Turbo C/C++/Borland C++ ............................ ii Power C ............................................ ii Zortech C++ ........................................ iii INTRODUCTION ........................................... 1 Defining Windows .................................... 1 Properties of Windows ............................... 1 Writing to Overlapping Windows ...................... 2 Window Ranks ........................................ 2 Detection of Video Hardware ......................... 2 Window Coordinates .................................. 2 Video Attributes .................................... 3 Direct Screen Writes and BIOS Screen Updates ........ 4 Video Paging ........................................ 5 Error Codes ......................................... 6 Window Manager ...................................... 8 MANDATORY FUNCTIONS AND HEADER FILES ................... 9 WindowInitializeSystem() ............................ 9 CREATING WINDOWS ....................................... 10 The WINDOW structure and WPOINTER structure pointer . 10 WindowSaveInitial() ................................. 10 WindowInitialize() .................................. 11 CREATE_VIDEO_ATTRIBUTE() macro ...................... 12 Box types ........................................... 12 OPENING WINDOWS FOR READING AND WRITING ................ 15 WindowOpen() ........................................ 15 DISPLAYING WINDOWS ..................................... 16 The WindowDisplay() function and Explosion Effects .. 16 Displaying Multiple Windows ......................... 19 CLOSING WINDOWS ........................................ 21 WindowClose() ....................................... 21 WindowFree() ........................................ 22 WindowCloseAll() .................................... 23 WindowFreeAll() ..................................... 24 CENTERING WINDOWS ON THE SCREEN ........................ 25 WindowCenter() ...................................... 25 The C Window Library CHANGING WINDOW CHARACTERISTICS ........................ 27 WindowChangeTextAttribute() ......................... 27 WindowChangeBorderAttribute() ....................... 28 WindowDrawBorder() .................................. 28 WindowRemoveBorder() ................................ 30 WindowResizeHeight() ................................ 30 WindowResizeWidth() ................................. 31 WRITING TEXT TO WINDOWS ................................ 33 Null Terminated Write Functions ..................... 33 WindowWriteString() .............................. 33 WindowWriteStringAttr() .......................... 34 WindowWriteCenterString() ........................ 35 WindowWriteCenterStringAttr() .................... 36 WindowWriteStringCC() ............................ 36 WindowWriteStringCCAttr() ........................ 37 WindowWriteStringRJ() ............................ 38 WindowWriteStringRJAttr() ........................ 39 Length Controlled Write Functions.................... 40 WindowWriteCharacters() .......................... 40 WindowWriteAttributes() .......................... 41 WindowWriteCharAndAttr() ......................... 42 WindowWriteCharactersAttr() ...................... 43 WindowWriteRepeatAttribute() ..................... 44 WindowWriteRepeatCharacter() ..................... 45 Formatted Write Functions ........................... 46 Where output is placed in the window ............. 46 WindowSetWrap() .................................. 46 WindowPrintf() ................................... 47 WindowPrintfAttr() ............................... 48 WRITING TITLES TO WINDOWS .............................. 50 WindowTitleTop() .................................... 51 WindowTitleBottom() ................................. 52 WindowTitleTopAttr() ................................ 53 WindowTitleBottomAttr() ............................. 54 READING CHARACTERS AND ATTRIBUTES FROM WINDOWS ......... 56 WindowReadCharacters() .............................. 56 WindowReadAttributes() .............................. 57 WindowReadCharAndAttr() ............................. 58 HIDING WINDOWS ......................................... 60 WindowHide() ........................................ 60 CREATING COPIES OF A WINDOW ............................ 62 WindowCopy() ........................................ 62 The C Window Library SCROLLING TEXT IN WINDOWS .............................. 64 WindowScroll() ...................................... 64 WindowScrollRegion() ................................ 65 WindowScrollAttr() .................................. 66 WindowScrollRegionAttr() ............................ 67 CLEARING WINDOWS ....................................... 69 WindowClear() ....................................... 69 WindowClearAttr() ................................... 70 WindowClearRegion() ................................. 70 WindowClearRegionAttr() ............................. 71 WRITING WINDOW CONTENTS TO A FILE ...................... 73 WindowWriteTextToFile() ............................. 73 SHADOWING WINDOWS ...................................... 75 WindowDrawShadow() .................................. 75 WindowRemoveShadow() ................................ 77 SEE-THRU WINDOWS ....................................... 78 WindowMakeSeeThru() ................................. 78 WindowMakeNormal() .................................. 79 MOVING AND SLIDING WINDOWS ............................. 80 WindowMove() ........................................ 80 WindowSlide() ....................................... 81 CURSOR POSITIONING IN WINDOWS .......................... 82 Cursor Maintenance in The C Window Library .......... 82 Creating Cursor Shapes .............................. 82 WindowChangeCursor() ................................ 82 WindowMoveCursor() .................................. 83 WindowGetCursorShape() .............................. 84 WindowGetCursorPosition() ........................... 85 GETTING WHICH WINDOW OCCUPIES A LOCATION ............... 87 WindowWhich() ....................................... 87 GETTING INPUT FROM WINDOWS ............................. 88 Input Manager ....................................... 88 Regular Expressions ................................. 88 Editing Input ....................................... 93 Last Key Value ...................................... 95 Default Cursor Types and Editing Mode ............... 96 Editing using a character mask ...................... 97 The C Window Library Editing Functions ................................... 97 WindowGetString() ................................ 97 WindowGetStringAttr() ............................ 99 WindowGetMaskString() ............................ 100 WindowGetMaskStringAttr() ........................ 102 Getting Passwords ................................ 103 WindowGetPassword() ........................... 103 WindowGetPasswordAttr() ....................... 104 WindowGetMaskPassword() ....................... 105 WindowGetMaskPasswordAttr() ....................106 Undefined Keystroke Processing ................... 107 The undef_fkey_func and undef_akey_func function pointers ................. 107 Specifying when to call an undefined key function in a Regular Expression ...... 108 Return Values To The Input Manager .......... 109 Input Options .................................... 112 CHECKREGEXP and the reg_exp_error_func function pointer ........................... 113 THE num_chars_entered_func FUNCTION POINTER ...... 116 Other Input releated functions ................... 117 TranslateStringToMaskString() .................... 117 TranslateMaskStringToString() .................... 119 VIRTUAL WINDOWS ........................................ 121 Using Windows as Viewports .......................... 121 Attributed and Non-Attributed Virtual Windows ....... 121 Virtual Window's Logical Cursor ..................... 122 CREATING VIRTUAL WINDOWS ............................ 123 VirtualInitialize() .............................. 123 ASSIGNING VIEWPORTS AND CLOSING VIEWPORTS ........... 125 WindowAssignToVirtual() .......................... 125 Out of bounds Coordinates ........................ 126 WindowCloseViewport() ............................ 127 WRITING TEXT TO VIRTUAL WINDOWS ..................... 129 Null Terminated String Functions ................. 129 VirtualWriteString() .......................... 129 VirtualWriteStringAttr() ...................... 130 VirtualWriteCenterString() .................... 131 VirtualWriteCenterStringAttr() ................ 132 VirtualWriteStringCC() ........................ 133 VirtualWriteStringCCAttr() .................... 134 VirtualWriteStringRJ() ........................ 135 VirtualWriteStringRJAttr() .................... 136 The C Window Library Length Controlled Functions ...................... 137 VirtualWriteCharacters() ...................... 137 VirtualWriteAttributes() ...................... 138 VirtualWriteCharAndAttr() ..................... 139 VirtualWriteRepeatAttribute() ................. 140 VirtualWriteRepeatCharacter() ................. 141 Formatted Write Functions ........................ 142 Format String ................................. 142 Where Output is Placed ........................ 142 VirtualSetWrap() .............................. 142 VirtualPrintf() ............................... 143 VirtualPrintfAttr() ........................... 144 READING CHARACTERS AND ATTRIBUTES FROM VIRTUAL WINDOWS .............. 146 VirtualReadCharacters() .......................... 146 VirtualReadAttributes() .......................... 147 VirtualReadCharAndAttr() ......................... 148 REPOSITIONING THE VIEWPORT .......................... 150 WindowPositionViewport() ......................... 150 SCROLLING THE VIEWPORTS ............................. 154 WindowScrollVirtual() ............................ 154 WRITING VIRTUAL WINDOW CONTENTS TO A FILE ........... 157 VirtualWriteTextToFile() ......................... 157 MOVING THE LOGICAL CURSOR ........................... 159 VirtualMoveCursor() .............................. 159 VirtualGetCursorPosition() ....................... 159 CLEARING VIRTUAL WINDOWS ............................ 161 VirtualClear() ................................... 161 VirtualClearAttr() ............................... 162 VirtualClearRegion() ............................. 162 VirtualClearRegionAttr() ......................... 163 FREEZING VIEWPORTS .................................. 165 WindowFreeze() ................................... 165 DISPOSING OF VIRTUAL WINDOWS ........................ 167 VirtualFree() .................................... 167 The C Window Library INTRODUCTION TO MENU SYSTEM ............................ 169 Menu Manager ........................................ 169 Necessary "include" files ........................... 169 POP-UP MENUS ........................................ 170 Description ...................................... 170 Windows and Virtual Windows ...................... 170 CREATING POP-UP MENUS ............................... 171 The POPUP_MENU_ENTRY structure ................... 171 Defining Hotkeys .............................. 172 Assigning the function to perform ............. 173 Coloring Popup Menus ............................. 173 Creating Popup Menu Entries Dynamically .......... 174 PopupCreateMenu() function ....................... 179 Popup Menu Options ............................ 180 Default Popup Window and Creating Your own Windows ............. 182 Default Virtual Window and Creating Your own Virtual Windows ....... 184 Accessing Popup Windows and Virtual Windows ... 184 Warnings ...................................... 185 Return Values for PopupCreateMenu() ........... 185 SELECTING FROM POPUP MENUS .......................... 187 PopupSelectMenu() function ....................... 187 Values passed to menu function ................ 189 Values returned to menu manager ............... 189 Return Values for PopupSelectMenu() ........... 190 SETTING OPTIONS IN POPUP MENUS ...................... 191 The PopupSetOptions() function ................... 191 Setting Multiple Options ...................... 192 Setting the PopupSetConfirmFunction() ......... 192 Return Values for PopupSetOptions() function .. 193 MAKING MENU ENTRIES AVAILABLE AND UNAVAILABLE ....... 194 PopupMakeEntryAvailable() and PopupMakeEntryUnavailable() functions ............ 194 POPUPOVERRIDE option .......................... 194 Return Values for PopupMakeEntryAvaialble() and PopupMakeEntryUnavailable() functions ............ 194 CHANGING THE MENU ENTRY STRINGS ..................... 196 PopupChangeEntryString() function ................ 196 Return Values for PopupChangeEntryString() function ................ 196 The C Window Library REDEFINING MENU KEYS ................................ 197 Setting Global Key Definitions and the popup_key_definition Array ............ 197 Setting Local Key Definitions .................... 197 PopupAssignKeys() function .................... 198 Return Values for PopupAssignKeys() function .. 198 PROCESSING UNDEFINED KEYS ........................... 199 The popup_undef_key function pointer ............. 199 Values returned to menu manager ............... 199 PRE-INPUT FUNCTION .................................. 203 Setting the global_popup_prefunc function pointer .............. 203 DISPOSING OF POPUP MENUS ............................ 205 PopupMenuFree() .................................. 205 Return Values for PopupMenuFree() ................ 205 BAR MENUS .............................................. 206 Description ......................................... 206 Windows and Virtual Windows ......................... 206 CREATING BAR MENUS .................................. 207 The BAR_MENU_ENTRY structure ..................... 207 Defining Hotkeys .............................. 208 Assigning the function to perform ............. 209 Coloring Bar Menus ............................... 209 Creating Bar Menu Entries Dynamically ............ 210 BarCreateMenu() function ......................... 214 Bar Menu Options .............................. 215 Default Bar Menu Window and Creating Your own Windows .......... 217 Accessing bar menu windows .................... 219 Warnings ...................................... 219 Return Values for BarCreateMenu() ............. 219 SELECTING FROM BAR MENUS ............................ 221 BarSelectMenu() function ......................... 221 Values passed to menu function ................ 223 Values returned to menu manager ............... 223 Return Values for BarSelectMenu() ............. 223 SETTING OPTIONS IN BAR MENUS ........................ 225 The BarSetOptions() function ..................... 225 Setting Multiple Options ...................... 226 Setting the BarSetConfirmFunction() ........... 226 Return Values for BarSetOptions() function .... 227 The C Window Library MAKING ENTRIES AVAILABLE AND UNAVAILABLE ............ 228 BarMakeEntryAvailable() and BarMakeEntryUnavailable() functions .............. 228 BAROVERRIDE option ............................ 228 Return Values for BarMakeEntryAvaialble() and BarMakeEntryUnavailable() functions .............. 228 CHANGING THE MENU OPTIONS STRING .................... 230 BarChangeEntryString() function .................. 230 Return Values for BarChangeEntryString() function ...................................... 230 REDEFINING THE MENU KEYS ............................ 232 Setting Global Key Definitions and the bar_key_definition Array ............... 232 Setting Local Key Definitions .................... 232 BarAssignKeys() function ...................... 232 Return Values for BarAssignKeys() function .... 233 PROCESSING UNDEFINED KEYS ........................... 234 The bar_undef_key function pointer ............... 234 Values returned to menu manager ............... 234 PRE-INPUT FUNCTION .................................. 237 Setting the global_bar_prefunc function pointer... 237 DISPOSING OF BAR MENUS .............................. 239 BarMenuFree() function ........................... 239 Return Values for BarMenuFree() .................. 239 PULLDOWN MENUS ......................................... 240 Description ......................................... 240 Bar Menu and Popup Menu levels ...................... 240 CREATING PULLDOWN MENUS ............................. 241 The PulldownCreateMenu() function ................ 242 Automatic Adjustment of Popup Windows ......... 244 Return values for PulldownCreateMenu() ........... 247 SELECTING FROM PULLDOWN MENUS ....................... 248 The PulldownSelectMenu() function ................ 248 Immediate Mode ................................ 248 Values passed to the selected menu function ... 249 Values returned to the menu manager ........... 249 Return Values for PulldownSelectMenu() ........ 249 The C Window Library REDEFINING KEY DEFINITIONS .......................... 250 REDEFINING KEY DEFINITIONS FOR POPUP MENUS ....... 251 Setting Popup Menu Global Key Definitions ..... 251 Setting Popup Menu Local Definitions .......... 252 REDEFINING KEY DEFINITIONS FOR THE BAR MENU ...... 253 Setting bar menu global key definitions ....... 253 Setting Bar Menu Local definitions ............ 253 PROCESSING UNDEFINED POPUP MENU KEYS ................ 254 PROCESSING UNDEFINED BAR MENU KEYS .................. 255 DISPOSING OF PULLDOWN MENUS ......................... 256 The PulldownMenuFree() function .................. 256 The PulldownMenuFreeAll() function ............... 256 SUMMARY OF PULLDOWN MENUS ........................... 257 EXAMPLE OF PULLDOWN MENU SYSTEM ..................... 258 MISCELLANEOUS FUNCTIONS ................................ 262 SETTING AND CHECKING VIDEO PAGES .................... 262 CheckVideoPage() ................................. 262 SetActiveVideoPage() function .................... 263 SetVisibleVideoPage() function ................... 264 GENERAL STRING WRITING FUNCTIONS .................... 266 VideoWriteString() ............................... 266 VideoWriteStringAttr() ........................... 267 VideoWriteAttributes() ........................... 267 VideoWriteCenterString() ......................... 268 VideoWriteCenterStringAttr() ..................... 269 VideoWriteCharAndAttr() .......................... 269 VideoWriteStringCC() ............................. 270 VideoWriteStringCCAttr() ......................... 271 VideoWriteStringRJ() ............................. 271 VideoWriteStringRJAttr() ......................... 272 VideoPrintf() .................................... 273 VideoPrintfAttr() ................................ 273 The C Window Library READING CHARACTERS AND ATTRIBUTES FROM THE SCREEN ... 275 VideoReadCharacters() ............................ 275 VideoReadAttributes() ............................ 275 VideoReadCharAndAttr() ........................... 276 DRAWING BOXES ....................................... 277 VideoDrawBox() ................................... 277 VideoDrawBoxAttr() ............................... 277 SAVING AND RESTORING SCREEN IMAGES .................. 279 VideoSave() ...................................... 279 VideoMove() ...................................... 280 VideoRestore() ................................... 280 VideoFree() ...................................... 281 CLEARING SCREENS .................................... 282 ClearScreen() .................................... 282 ClearRegion() .................................... 282 SCROLLING SCREENS ................................... 284 ScrollScreenUp() ................................. 284 ScrollScreenDown() ................................284 CHANGING THE VIDEO MODE ............................. 286 SetVideoMode() ................................... 286 CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE SCREEN .............. 287 Changing rows .................................... 287 AdjustScreenInfo() ............................ 287 AdjustGlobalData() ............................ 288 SetVideoRows() ................................ 288 Changing columns ................................. 291 40 column and 80 column modes ................. 291 Modes higher than 80 columns .................. 292 CURSOR MANIPULATION ................................. 294 MoveCursor() ..................................... 294 ChangeCursor() ................................... 294 GetCursorShape() ................................. 295 GetCursorPosition() .............................. 295 HideCursor() ..................................... 296 BlockCursor() .................................... 296 ThinCursor() ..................................... 296 The C Window Library GETTING VIDEO INFORMATION ........................... 298 VIDEO_CONFIG structure ........................... 298 GetVideoBiosInfo() ............................... 298 TIMED DELAYS ........................................ 300 delay() .......................................... 300 SOUND FUNCTIONS ..................................... 301 sound() and nosound() ............................ 301 MakeSound() ...................................... 301 ERROR HANDLING ...................................... 303 The window_error_func function pointer ........... 303 USING A MOUSE WITH THE C WINDOW LIBRARY ............. 306 Installing the Mouse Library ..................... 306 Include Files .................................... 306 Initializing the Mouse with MouseInitializeSystem().......... 306 Turning off the mouse with MouseRestoreSystem() .. 307 Using a mouse with popup menus ................... 308 Popup Menu's prefunction for mouse ........... 310 Using a mouse with bar menus ..................... 311 Using a mouse with pulldown menus ................ 313 Changing the mouse defaults ...................... 314 WINDOW AND VIRTUAL WINDOW MACROS .................... 315 MENU MACROS ......................................... 318 Popup Menu Macros ................................ 318 Bar Menu Macros .................................. 320 Pulldown Menu Macros ............................. 321 VIDEO MACROS ........................................ 322 BOX MACROS .......................................... 326 EXPLOSION MACROS .................................... 327 KEYBOARD MACROS ..................................... 328 Keyboard Idle Function ............................ 329 Keyboard Intercept Function ....................... 330 Checking for mouse presses ........................ 331 CURSOR MACROS ....................................... 333 IMPORTANT GLOBAL VARIABLES ............................. 334 The C Window Library PRELIMINARIES ------------- Congratulations on using The C Window Library; the easiest to use, most powerful, inexpensive C user interface library! Before we start talking 'C', we will discuss briefly on how to compile and link programs using The C Window Library. The following discussion is very brief. For more in depth information on make files, project files, link options, etc. please consult the various documentation supplied with the compiler that you are working with. The default word/byte alignment scheme was used when compiling all the libraries. In other words, all modules used by The C Window Library were compiled without the use of the word/byte alignment switch being used. Microsoft / Quick C ------------------- When compiling your programs, you must make sure that the constant MSC is defined. An example of how you would do this as follows: cl -Ax -DMSC -Ihfiles prog1.c /link mswinx.lib msmousex.lib the -Ax is the model used for compilation. The x stands for either S for small, M for medium, C for compact, or L for large. The -D option defines a constant, which in this case is MSC. You must use the -D switch with MSC as the constant. If not, you will get either syntax errors, link errors, or runtime errors. The -I option tells the compiler that the .h files are located in a directory on the default drive called hfiles. The /link option links the resulting object files (prog1.obj) with The C Window Library file mswinx.lib, where x stands for S, M, C, or L. The mouse library msmousex.lib, where x stands for S, M, C, or L, is necessary only if you plan to use the mouse in your application. The other method is to create a make file. If you are using the integrated environment of Quick C or using the Programmers Work Bench (PWB) for Microsoft C 6.0, you can create your make files by selecting the files you want to compile, and the libraries you want to link with and letting these integrated environments create the make file automatically. If you are more advanced you can create your make files by yourself without the aid of these programs. Consult the documentation for more information on make files. i Turbo C/TurboC++/Borland C++ ---------------------------- If you will use the integrated environment, you must create a project file. This project file specifies the source code modules, object code modules, and libraries that will be linked in to produce an executable file. If you use the Turbo C Version 2.0 integrated environment, you must edit this file yourself. If you use the Turbo C++ or Borland C++ integrated environment, use the automatic Project File creator. You can also use make files to link in your program. Make sure that the desired library from The C Window Library is specified. You can also use the TCC.EXE (or BCC if you are using Borland C++) command line compiler with the desired library specified on the command line. Consult the Turbo C/C++ documentation on using make files and using the integrated environment. The default structure alignment was used to compile the libraries, which is byte alignment. An example of using the TCC.EXE (BCC.EXE) command line is as follows: tcc -mm -G -r -ihfiles prog1.c tcwinm.lib tcmousem.lib The following command line uses -mm for the medium memory model, -G to optimize for speed, -r for usage of register variables, and -i to tell the compiler that the header files are located in a directory on the default drive called hfiles. The mouse library, tcmousem.lib, is necessary only if you plan to use the mouse in your application. Power C ------- If you are using the POWER C compiler from Mix Software, you must define the constant POWERC on the command line. pc -dPOWERC -mm -ihfiles prog1.c You must have the constant POWERC defined on the pc.exe command line using the -d option. If not, you may get syntax, link, or runtime errors. The -mm tells the compiler to use the medium memory model, and the -i option tells the compiler that there are .h files located on the default drive in the directory hfiles. Depending on the number of windows your application will use and the code size, you will have to use different stack and heap options in the Power C linker, pcl. An example of this is as follows: ii pcl [20k,30k,200k] a;pcwinm;pcmousem This will link the object file a.mix with the pcwinm.mix library with 20k of stack space, 30k of near heap space, and 200k of far heap space. If your application has many or very large virtual windows, you should use the maximum far heap space allowable. If your program has many windows, you should increase the near heap space parameter, or use the pcwinl.mix library and increase the far heap space parameter. If your program has recursive or deeply nested functions, you should increase the stack parameter. However the stack and near heap space cannot exceed 64k. This includes global and static declarations in the program. The mouse library, pcmousex, is necessary only if you plan to use the mouse in your application. Zortech C++ ----------- If you are using the Zortech C++ compiler, you should use the following options when compiling your program with The C Window Library: ztc -o -b -p -mm prog1.c zcwinm.lib zcmousem.lib The -o option turns on the global optimizer. The -b option lets ztc know to handle large programs. The -p turns off auto-prototyping. The -mm option lets the compiler use the medium memory model. The programs prog1.c is compiled using these options and then linked with the medium memory model of The C Window Library's Zortech version, namely zcwinm.lib. The mouse library, zcmousem.lib, is necessary only if you plan to use the mouse in your application. iii INTRODUCTION ------------ Defining Windows ---------------- A window is an area of the screen that is separate and independent from the other areas of the screen. With windows, you can scroll, write text, delete text, etc. in a defined section of the screen. An example of windows in application programs are the resident memory utilities that pop up on the screen when invoked, and restore the text to its original state when the resident application is terminated. Sidekick is a good example of what you can do with windows. As a matter of fact, most professional programs use windows in some manner. Some applications use windows to make pulldown menus i.e. the integrated environment in the Turbo languages and in Microsoft Quick C's integrated environment. Other applications such as text editors and word processors use windows to display and edit a files contents. With The C Window Library, you can create professional looking application program easily and without worrying about the tricky details of window management. At your disposal are tools that can help you create pull-down menus, popup menus, bar menus, and just fast output. Properties of Windows --------------------- Windows should have the following properties: - more than one window can be displayed on the screen simultaneously. - windows are allowed to overlap without disturbing the contents of the windows underneath. - a window that is under a pile of windows can be brought to the top. - a window that is under a pile of windows can be written to without interfering with other windows. - windows can be disposed of when not needed, and erased from the screen. When erased, the contents of the screen underneath the window is restored. - windows can be written to at any time. - the window application should automatically detect the type of video hardware used. - the window functions should return an error if something goes wrong. Page 1 The C Window Library Page 1 Writing to Overlapping Windows ------------------------------ With The C Window Library, if a window does overlap another window, this overlap will be displayed on the physical screen. The C Window Library allows you to direct output to any window at any time. When output is written to a window, the window contents are updated in memory, but only the visible portions of the window will be updated on the screen. Window Ranks ------------ The rank order of the windows on the screen will determine which window has priority of the screen. Windows with lower rank numbers overlap windows with higher rank numbers. The lowest rank number is 1, and the highest is 254. If a new window is opened with the same rank number as another previously opened window, the new window takes over the rank position, and the previous window's rank is increased by 1. If there is a window with the same rank as the previous window's new rank, its rank is increased by 1 etc. When a window is closed, all windows with a higher rank number are decreased by 1. Detection of Video Hardware --------------------------- With The C Window Library, automatic detection of the type of video hardware is necessary. Since The C Window Library can write directly to screen memory, the starting memory address of screen memory must be known. Depending on the video adapter, the starting address of screen memory is different. For monochrome systems, the starting address is different from a color system. If the window routines think that they are writing to a color system instead of a monochrome system, crazy things will probably happen. For most adapters, The C Window Library will detect them and assign the starting address of screen memory to a global variable, so there is no need to specify the starting address yourself. Window Coordinates ------------------ A position on the screen can be specified as a pair of numbers. These numbers will denote the row and column of the desired position. Rows and columns are numbered from 1 to the maximum row or column number. The upper left hand corner of the screen would be at row 1, column 1. For Page 2 The C Window Library Page 2 simplicity, row y, column x will be abbreviated as (y,x). The position (1,1) is called the home position. However, when specifying a position in a window, this position is numbered relative to the window itself. No matter where a window resides on the screen, the upper left position of the window is (1,1), the second row of the window is row 2, the fourth column is column 4, etc. The window coordinates are called window relative coordinates. There are some window functions that require you to enter physical screen (absolute) coordinates, but for most functions, a window relative position would be needed. For example: ----------------------------------------------------------- |(1,1) (80,1)| | | | Valid Absolute Screen Coordinates | | For 80 x 25 Screen | | | | This window opened at absolute (12,15) | | | | | v | | ----------------------- | | |(1,1) (1,30)| | | | | | | | | | | |(14,1) (14,30)| | | ----------------------- | |(1,25) (80,25)| ----------------------------------------------------------- Video Attributes ---------------- With The C Window Library, a window can have an assortment of colors for text and background. Each character that is displayed on the screen has its corresponding attribute byte. The attribute byte is an 8-bit quantity that specifies a character's color, intensity, and blink status. The format of the attribute byte is as follows: 7 6 5 4 3 2 1 0 -------------------------- |B | bground |I|fground | |__|_________|_|_________| The B is the blink bit and the I is the intensity bit. Bits 0 thru 2 is a color code for the foreground (text) color. Bits 4 thru 6 determine the color code for the background (screen) color. Page 3 The C Window Library Page 3 If the blink bit is 1, then the character will blink. If the intensity bit is on, the character will appear brighter than usual. Some monitors cannot display high intensity characters, so the intensity bit may not change the characters brightness at all. Here is a list of color values along with the color they represent: Value Color Value Color 0 Black 8 Gray 1 Blue 9 Light blue 2 Green 10 Light green 3 Cyan 11 Light cyan 4 Red 12 Light red 5 Magenta 13 Light magenta 6 Brown 14 Yellow 7 White 15 Intense white If the video system is a monochrome system, the color values specified above will give unpredictable results if not used carefully. Monochrome systems also have an underline mode, that color systems (unless if you program the EGA or VGA adapters) cannot display. Upcoming is a list of color values that should work on monochrome systems along with the type of display that will be produced: Display Background Foreground No display 0 0 Underline 0 1 Normal Video 0 7 Reverse Video 7 0 When programming a monochrome system, you can change the values of the colors not supported to black and white combinations supported on the monochrome system. For example, you can change the light green color's value from 10 to 7. Now if light green is selected as a foreground color and the background color is black, you will have a normal video display on a monochrome system. Direct Screen Writes and BIOS Screen Updates -------------------------------------------- By default, The C Window Library writes directly to screen memory. This results in very fast screen output. If you have ever wondered how commercial programs can display output so rapidly on the screen, direct screen writing is Page 4 The C Window Library Page 4 the major reason. The disadvantage of writing directly to the screen is that it is ill- behaved with programs like Microsoft Windows or Quarterdeck's DesQView (although DesQView386 running on an 80386 machine is well behaved with direct screen writes). Also on some color systems, the screen output is so fast that the video display produces "snow" on the screen. However, The C Window Library will automatically detect whether "snow" should be checked when writing directly to the screen. The old IBM Color Graphics Adapters suffer from this problem, but most other adapters including monochrome, Hercules, EGA, VGA, and newer CGA's do not suffer from this problem. When checking for snow, the screen writes are not as fast as when there is no snow checking, but it is fast enough. The other method of updating the screen is by making a call to the video functions contained in the ROM BIOS. BIOS stands for Basic Input Output System. The BIOS provides routines that are needed for the operation of the computer. Some of these routines are video functions needed to write characters and attributes, move the cursor, and scroll portions of the screen. Using the BIOS instead of writing directly to screen memory results in much slower screen updates, but will be compatible with programs like Microsoft Windows and DesQView. With The C Window Library, you are allowed to use either method. Video Paging ------------ Since most video display adapters have enough memory to store more than one screen of characters, these video adapters will support multiple video pages. With multiple video pages, you can write to a hidden video page and then display the entire video page instantaneously. The only adapter that does not support video paging is the Monochrome Display Adapter (MDA). All CGA's, EGA's and VGA's support multiple video pages. The maximum number of pages a card will support is determined by the amount of RAM included in the video board, and the maximum number of characters that can be displayed on each page. A list of the maximum number of video pages in each mode for each card is as follows: Page 5 The C Window Library Page 5 BIOS Mode Max. # Mode # Type Adapter of pages ---- ---- ------- -------- 0,1 Text CGA, EGA, VGA 8 2,3 Text CGA, 4 EGA, VGA 8 7 Text MDA, Hercules 1 EGA, VGA 8 With The C Window Library, the video page displayed on the screen is called the visible page. When creating a window, its page number is recorded. When updating windows, the video page number where the window resides is used to direct the output to the appropriate video page. There are also functions in The C Window Library that allow you to switch video pages. With these routines, you can create very sophisticated user interfaces. If you are using a clone Hercules Monochrome adapter, you may have access to more than one video page. The original Hercules card has only one page of text memory. The problem of accessing the other pages in the clone cards is that there is no universal way to determine how many pages that the card has. If you are writing an application that targets a specific Hercules clone card, and you want to take advantage of the multiple pages, you can modify a global variable that contains the maximum number of available video pages, as well as the array that contains the segment:offset of each video page. Make sure you have the full documentation for the card, or know off-hand the number of pages and their addresses. Error Codes ----------- With most of The C Window Library functions, window_error_code, which is a global integer variable is set to an error number when a function cannot be completed. Throughout this documentation, you are to assume that window_error_code is set to any error condition that is documented for each function. The window_error_code variable IS NOT reset when a function has been completed successfully. A list of error codes is as follows: Error Constant Error Code Definition -------------- ---------- ---------- NO_HEAP_MEM -1 Not enough memory to allocate from the heap. BAD_DISPLAY_PAGE -2 Video Display page is invalid. INVALID_VIDEO_MODE -3 Invalid video mode. Page 6 The C Window Library Page 6 INVALID_ROWS -4 Invalid number of screen rows specified. BAD_WINDOW -100 Window does not exist. BAD_WINDOW_SIZE -101 Window dimensions are invalid. WINDOW_NOT_OPEN -102 Window not open for read/write. WINDOW_BOUND -103 Coordinates specified for window are out of bounds. MAX_WINDOW -104 Maximum number of windows defined. WINDOW_INV_PARAM -105 An invalid parameter was encountered in the function call. NO_INPUT_CHARS -106 Trying to input a field of 0 characters. BAD_V_WINDOW -200 The virtual window does not exist. END_V_WINDOW -201 Internally used by The C Window Library. V_WINDOW_BOUND -202 Coordinates specified for virtual window are out of bounds. MAX_V_WINDOW -203 Maximum number of virtual windows defined. NO_ATTRIB -204 Virtual window does not have attributes. FILE_NO_EXIST -300 File does not exist. FILE_CANT_CLOSE -301 Cannot close file. FILE_CANT_OPEN -302 Cannot open file. MENU_ENTRY_INVALID -400 An invalid menu entry was specified. Page 7 The C Window Library Page 7 Window Manager -------------- The window manager is the code in The C Window Library that handles window initialization, movement, coloring, and other functions that control window management. Page 8 The C Window Library Page 8 MANDATORY FUNCTIONS AND HEADER FILES ------------------------------------ The only mandatory function is WindowInitializeSystem(), explained below. The window.h header file must be included in any module that will call functions included in The C Window Library. WindowInitializeSystem() ------------------------ This function MUST be called before any other function defined in The C Window Library. This function also sets global variables, so it is also mandatory to call WindowInitializeSystem() before accessing any global variables defined by The C Window Library. WindowInitializeSystem() detects the type of video display used, the number of rows and columns that the screen currently displays, and initializes data structures and global variables. Example: #include "window.h" main() { WindowInitializeSystem(); /* Initialization function */ /* Now it is safe to use C Window Library functions and global variables */ } There is no return value for WindowInitializeSystem(). Page 9 The C Window Library Page 9 CREATING WINDOWS ---------------- We will now look how a window is created by defining a WINDOW, WPOINTER, and using the WindowSaveInitial() and WindowInitialize() function. The WINDOW structure and WPOINTER structure pointer --------------------------------------------------- When a window is created, the upper left hand column and row, the width, height, etc. must be recorded. It would be very tedious if for every function call that acts on these windows we have to specify width, height, upper left hand row, etc. as function parameters. The C Window Library conveniently has a structure called WINDOW, and its corresponding pointer called a WPOINTER to alleviate these problems. When a window is created, its characteristics are stored in a WINDOW structure, and most functions require that a pointer to this structure be passed. This pointer is called a WPOINTER. By only referring to the WPOINTER, argument lists to functions become much shorter. WindowSaveInitial() ------------------- The WindowSaveInitial() function saves the base screen as a window. This MUST be called prior to creating any windows. Here is a prototype: int WindowSaveInitial(int page) The page argument is the video page of the base screen to save. If you are creating windows that will be manipulated on video page 0, you must call WindowSaveInitial() with 0 as the argument: #include "window.h" main() { WindowInitializeSystem(); /* Initialize global variables */ WindowSaveInitial(0); /* Save video page 0's base screen */ } Page 10 The C Window Library Page 10 In most applications, the initial screen page is page 0. However, it is safer to use the global variable active_video_page (explained in the IMPORTANT GLOBAL VARIABLES section) to determine the page. If you are changing video pages in an application, the new page has to be initialized with WindowSaveInitial() so that the window manager updates the screen properly when moving windows, hiding windows, etc. This function must be called only once in an application for each screen page desired. If there is no error, WindowSaveInitial() returns NO_ERROR. If there is an error, WindowSaveInitial() returns the following values: BAD_DISPLAY_PAGE if the page desired does not exist, or was not detected by The C Window Library. NO_HEAP_MEM if there is no memory to save the initial screen. MAX_WINDOW if the maximum number of windows has already been defined. WindowInitialize() ------------------ The next function is WindowInitialize(). This function sets up a window with the position on the screen to place the window, width, height, colors, and box type. If successful, this function returns a new WPOINTER. Here is an example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,15,NORM,NORM,SINGLEBOX); ... } In the above example, we have defined a variable w as having a WPOINTER type. This variable will ultimately point to a valid WINDOW structure. The first argument to WindowInitialize() is a constant called BORDER. This tells the window manager that the window desired is going to have a border. If no border was desired, the constant would be NOBORDER. The second and third arguments tells the window manager the row and column of the screen where the upper left corner of the window will be located. Since the upper left corner of the screen is row 1, column 1, the upper left hand corner of the window will be placed at the upper left Page 11 The C Window Library Page 11 corner of the video screen. The fourth and fifth argument denotes the width and the height of the window. DO NOT INCLUDE THE BORDERS (if any) TO DETERMINE THE WIDTH AND HEIGHT OF THE WINDOW. Our window will have a width of 30 characters and a height of 15 characters. The sixth and seventh arguments are the video attributes of the inside of the window and the border respectively. The last argument tells us what type of border the window will have. We use the constant SINGLEBOX to tell the window manager that we want a window with a border made up of single lines. If there is no error, WindowInitialize() returns a valid WPOINTER. If there is an error, WindowInitialize() returns a WIN_NULL_PTR (a null window pointer) and sets window_error_code to one of the following values: NO_HEAP_MEM if there is not enough memory to allocate for the window structure. BAD_WINDOW_SIZE if the dimensions for the window are too large for the physical screen. MAX_WINDOW if there are > 254 windows defined. Even though there is a structure type called WINDOW, you should always use the pointer to the structure (WPOINTER) rather than the WINDOW structure itself. CREATE_VIDEO_ATTRIBUTE() macro ------------------------------ Please note the use of the macro CREATE_VIDEO_ATTRIBUTE() in the previous example to create an integer representing the foreground and background colors. This macro uses the first argument as the background color, and the second argument is the foreground color. In the above example we have a constant called NORM which uses CREATE_VIDEO_ATTRIBUTE() to create a black background and a white foreground color combination. Box types --------- For ease of use, There are predefined constants found in the vidsys.h header file that contains definitions of common border types. These constants are as follows: Page 12 The C Window Library Page 12 DOUBLEBOX -- defines border characters for double box windows. SINGLEBOX -- defines border characters for single box windows. MIXEDBOX1 -- defines double lines for top and bottom and single lines on the sides. MIXEDBOX2 -- defines single lines for top and bottom and double lines on the sides. HATCHBOX1 -- defines a 'dotty' box. HATCHBOX2 -- Another 'dotty' box. HATCHBOX3 -- Yet another 'dotty' box. SOLIDBOX1 -- defines a box of solid characters. SOLIDBOX2 -- defines another box of different solid characters. BLANKBOX -- defines a box with a blank border. When using these characters, do not get confused with a blank border. DOTTEDLINE -- defines a box with dotted lines. Although there are predefined border types in The C Window Library, you can define your own types. The window border characters are represented by an 8 byte character string. Each character in this string refers to a border character to be used in drawing the window border. A list of what each position in the string stands for is as follows: position Representation -------- --------------------------- 0 Upper left corner character. 1 Top line character. 2 Upper right corner character. 3 Left side character. 4 Right side character. 5 Bottom left corner character. 6 Bottom line character. 7 Bottom right corner character. This character string is sent to the window functions that call for a string of box drawing characters. For example, you can create your own customized set of characters with something like this: #define MYBOXCHARS "+-+||+-+" Page 13 The C Window Library Page 13 MYBOXCHARS is a literal string of box drawing characters. Using the rules of box drawing characters defined above, the upper left hand corner of the box is the plus sign, the top line is the hyphen, the upper right and corner is the plus sign, the left side is a pipe character, as is the right side, and the bottom part of the box is defined the same as the upper part. Then you would use it in a call to any function that asks for a box drawing string like this: w = WindowInitialize(BORDER, ... ,MYBOXCHARS); The '... ' are the other arguments that you would normally put for the WindowInitialize() function. Page 14 The C Window Library Page 14 OPENING WINDOWS FOR READING AND WRITING --------------------------------------- The next step is to allocate memory for the window's text buffer. This will allow writing and reading characters to the window even though it is not visible. WindowOpen() ------------ The WindowOpen() function is used to allocate memory for the window's text buffer. This function MUST be called if you are going to do many of the window functions. Here is the previous example with the WindowOpen() call: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,15,NORM,NORM,SINGLEBOX); WindowOpen(w); ... } The WindowOpen() function does not display the window. The argument tells the window manager what window to open. In this case we want to open our new window, w. The window buffer is cleared to spaces using the window's text attribute, and the border (if there is a border) is drawn internally. When a window is opened with WindowOpen(), you can then write or read characters to a window, move, scroll, etc. almost any function that you can do with a visible window. If there is no error, WindowOpen() returns NO_ERROR. If there is an error, WindowOpen() returns one of the following: 1) NO_HEAP_MEM if there is not enough memory to allocate for the window buffer. 2) BAD_WINDOW if the window does not exist. Page 15 The C Window Library Page 15 DISPLAYING WINDOWS ------------------ Now we will display the window we created in the previous example. The WindowDisplay() function and Explosion Effects -------------------------------------------------- The WindowDisplay() function displays a window. Here is the previous example with WindowDisplay() added to it: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,15,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); ... } The first argument to WindowDisplay() is the window to display, in our case, w is the window. The second argument is the rank order of the window. Since the rank order we desire is 1, this window will lie on top of all windows, unless another window is opened with a rank of 1. Remember, any window with a rank number n will have windows with rank n-1, n-2,...,1 to be displayed on top of it. You can change the rank order of a window at any time by calling WindowDisplay() with a different rank number. The third argument to WindowDisplay() is the explosion effect of the window when it is displayed. There are currently 12 ways to explode a window on the screen, numbered from 0 thru 11. Here is an overview of each effect: Defined Constant Value Effect ---------------- ----- ------ NOEFFECT 0 ┌─────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ Page 16 The C Window Library Page 16 EXPLODE 1 ┌─────────────────┐ │ ^ │ │ | │ │ | │ │<-- -->│ │ │ │ | │ │ | │ │ v │ └─────────────────┘ CONTRACT 2 ┌─────────────────┐ │ | │ │ | │ │ v │ │--> <--│ │ ^ │ │ | │ │ | │ └─────────────────┘ BRICKS 3 ┌────────────────┐ │█ █ █ █│ │ █ │ │ █ █ █ │ │ █ │ │ █ █ █ █ │ │█ █ │ └────────────────┘ ^ MIDDLEROWOUT 4 | ┌───────────────┐ └───────────────┘ | v TOPBOTTOMIN 5 ┌───────────────┐ └───────────────┘ | v Page 17 The C Window Library Page 17 ^ | ┌───────────────┐ └───────────────┘ TOPDOWN 6 ┌───────────────┐ └───────────────┘ | v ^ BOTTOMUP 7 | ┌───────────────┐ └───────────────┘ MIDDLECOLOUT 8 ┌┐ ││ ││ ││ <-││-> ││ ││ ││ └┘ LEFTRIGHTIN 9 ┌┐ ┌┐ ││ ││ ││ ││ ││ ││ ││-> <-││ ││ ││ ││ ││ ││ ││ └┘ └┘ Page 18 The C Window Library Page 18 LEFTTORIGHT 10 ┌┐ ││ ││ ││ ││-> ││ ││ ││ ││ └┘ RIGHTTOLEFT 11 ┌┐ ││ ││ ││ <-││ ││ ││ ││ ││ └┘ If there is no error, WindowDisplay() will return NO_ERROR. If there is an error, WindowDisplay() will return one of the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window was not open with WindowOpen(). Displaying Multiple Windows --------------------------- If you are creating multiple windows you can change the rank of the window by calling WindowDisplay() with a different rank number. Here is an example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) Page 19 The C Window Library Page 19 #define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red) #define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green) main() { int i; WPOINTER w1,w2,w3; /* pointers to a window structures */ WindowInitializeSystem(); WindowSaveInitial(0); w1 = WindowInitialize(BORDER,1,1,30,15,BLUEONBLACK,NORM, SINGLEBOX); /* define second window */ w2 = WindowInitialize(BORDER,3,3,30,15,REDONBLACK,NORM, DOUBLEBOX); /* define third window */ w3 = WindowInitialize(BORDER,5,5,30,15,GREENONBLACK,NORM, SINGLEBOX); WindowOpen(w1); /* make window 1 ok to write */ WindowOpen(w2); /* make window 2 ok to write */ WindowOpen(w3); /* make window 3 ok to write */ WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); WindowDisplay(w3,3,NOEFFECT); GET_KEY(); WindowDisplay(w2,1,NOEFFECT); GET_KEY(); WindowDisplay(w3,1,NOEFFECT); GET_KEY(); WindowDisplay(w1,1,NOEFFECT); GET_KEY(); } In the above program, w1, w2, and w3 are displayed with rank numbers of 1, 2, and 3, respectively. The ordering means that w1 will overlay w2, and w2 will overlay w3. Note that after the windows w1, w2, and w3 are initially displayed, they are redisplayed by making another call to WindowDisplay(). You can redisplay a window and change its rank by calling the WindowDisplay() function again. For example, w2 is redisplayed with a rank of 1. This promotes w2 to the top of the stack of displayed windows, and demotes w1 with a rank of 2. Each and every window has a unique rank number. The window manager keeps track of conflicts in rank numbers, and adjusts the data structures involved in maintaining the windows in working order. Therefore, there is really no need for you to remember whether a rank number is used or not. The macro GET_KEY() pauses the program until you press a key. Page 20 The C Window Library Page 20 CLOSING WINDOWS --------------- In this section, we will discuss closing windows with and without destroying the window pointer. WindowClose() ------------- The WindowClose() function hides a window from the screen and deallocates any memory that was allocated by the WindowOpen() function described in the previous section. This DOES NOT destroy the window pointer (WPOINTER), however you must call WindowOpen() again if you want to use this window again for most other window functions. Here is the prototype: int WindowClose(WPOINTER w, int effect) The first argument is the window. The second argument is the special effect to use when closing the window. This argument is only meaningful if the window is visible. For a list of effects refer back to the DISPLAYING WINDOWS section. This function can be used if you are short of memory, but you do not want to destroy the WPOINTER. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) #define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red) #define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green) main() { int i; WPOINTER w1,w2,w3; WindowInitializeSystem(); WindowSaveInitial(0); w1 = WindowInitialize(BORDER,1,1,30,15,BLUEONBLACK,NORM, SINGLEBOX); /* define second window */ w2 = WindowInitialize(BORDER,3,3,30,15,REDONBLACK,NORM, DOUBLEBOX); Page 21 The C Window Library Page 21 /* define third window */ w3 = WindowInitialize(BORDER,5,5,30,15,GREENONBLACK,NORM, SINGLEBOX); WindowOpen(w1); /* make window 1 ok to write */ WindowOpen(w2); /* make window 2 ok to write */ WindowOpen(w3); /* make window 3 ok to write */ WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); WindowDisplay(w3,3,NOEFFECT); GET_KEY(); WindowDisplay(w2,1,NOEFFECT); GET_KEY(); WindowDisplay(w3,1,NOEFFECT); GET_KEY(); WindowDisplay(w1,1,NOEFFECT); GET_KEY(); WindowClose(w2,NOEFFECT); GET_KEY(); WindowClose(w3,NOEFFECT); GET_KEY(); WindowClose(w1,NOEFFECT); } The example above calls WindowClose() on all three windows. If there are no errors, WindowClose() returns NO_ERROR. If there are errors, WindowClose() returns the following value: BAD_WINDOW if the window w does not exist. WindowFree() ------------ The WindowFree() function acts just like the WindowClose() function except that the WPOINTER is also deallocated. This means that the WPOINTER cannot be used anymore unless it is initialized again using WindowInitialize(), or is assigned to another valid WPOINTER. Here is the prototype: int WindowFree(WPOINTER w, int effect) Refer to WindowClose() for definitions of arguments and return values. Page 22 The C Window Library Page 22 WindowCloseAll() ---------------- The WindowCloseAll() function acts just like WindowClose() function except that all windows are closed on a desired video page. Here is the prototype: int WindowCloseAll(int page, int effect) The page argument is the video page of where the windows are located. Remember that The C Window Library allows displaying windows on video pages other than page 0 (default page). The effect argument is the special effect to use when closing the window. Refer to DISPLAYING WINDOWS for the list of special effects. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) #define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red) #define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green) main() { int i; WPOINTER w1,w2,w3; WindowInitializeSystem(); WindowSaveInitial(0); w1 = WindowInitialize(BORDER,1,1,30,15,BLUEONBLACK,NORM, SINGLEBOX); /* define second window */ w2 = WindowInitialize(BORDER,3,3,30,15,REDONBLACK,NORM, DOUBLEBOX); /* define third window */ w3 = WindowInitialize(BORDER,5,5,30,15,GREENONBLACK,NORM, SINGLEBOX); WindowOpen(w1); /* make window 1 ok to write */ WindowOpen(w2); /* make window 2 ok to write */ WindowOpen(w3); /* make window 3 ok to write */ WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); WindowDisplay(w3,3,NOEFFECT); WindowCloseAll(0,NOEFFECT); /* close all the windows */ } The example above calls WindowCloseAll() to close all three windows. Refer to WindowClose() for return values. Page 23 The C Window Library Page 23 WindowFreeAll() --------------- The WindowFreeAll() function acts just like WindowClose() function except that all windows are freed on a desired video page. Here is the prototype: int WindowFreeAll(int page, int effect) The page argument is the video page of where the windows are located. Remember that The C Window Library allows displaying windows on video pages other than page 0 (default page). The effect argument is the special effect to use when closing the window. Refer to DISPLAYING WINDOWS for the list of special effects. Refer to WindowCloseAll() for return values. Page 24 The C Window Library Page 24 CENTERING WINDOWS ON THE SCREEN ------------------------------- The C Window Library allows easy centering of windows on the screen. WindowCenter() -------------- The WindowCenter() function centers a window on the screen vertically, horizontally, or both. Here is the prototype: int WindowCenter(WPOINTER w, int option) The first argument is the window to center, and the second argument tells whether to center the window horizontally, vertically, or both. The options argument must be one of the following: Value of options Type of centering ------- ----------------- VERTCENTER vertical HORIZCENTER horizontal VERTCENTER | HORIZCENTER both horizontal and vertical Note the bitwise OR (|) between the constants VERTCENTER and HORIZCENTER for both horizontal and vertical centering. This function can be used on hidden windows and windows that have not been opened with WindowOpen(). Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); Page 25 The C Window Library Page 25 WindowCenter(w,VERTCENTER); /* center vertically */ GET_KEY(); WindowMove(w,1,1); GET_KEY(); WindowCenter(w,HORIZCENTER); /* center horizontally */ GET_KEY(); WindowMove(w,1,1); GET_KEY(); WindowCenter(w,VERTCENTER | HORIZCENTER); /* center both horizontal and vertical */ GET_KEY(); WindowFree(w,NOEFFECT); } If there are no errors, WindowCenter() returns NO_ERROR. If there is an error, the following value is returned: BAD_WINDOW if the window does not exist. Page 26 The C Window Library Page 26 CHANGING WINDOW CHARACTERISTICS ------------------------------- In this section, we will discuss changing the window attributes, border style, and the window's height and width. WindowChangeTextAttribute() --------------------------- This function changes the attribute of the text portion of the window. The text portion is the inside of the window. Here is a prototype: int WindowChangeTextAttribute(WPOINTER w, int color) where w is the WPOINTER to change the text attribute, and color is the new color. You can use the CREATE_VIDEO_ATTRIBUTE() macro to define the color. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowChangeTextAttribute(w,REVERSE); } If there is no error, WindowChangeTextAttribute() returns NO_ERROR. If there is an error, the following value is returned: BAD_WINDOW if the window does not exist. Page 27 The C Window Library Page 27 WindowChangeBorderAttribute() ----------------------------- This function changes the video attribute of the border of the window. If the window does not have a border, nothing is changed. Here is a prototype: int WindowChangeBorderAttribute(WPOINTER w, int color) where w is the WPOINTER to change the border attribute, and color is the new color. You can use the CREATE_VIDEO_ATTRIBUTE() macro to define the color. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowChangeBorderAttribute(w,REVERSE); } If there is no error, or if the window does not have a border, WindowChangeBorderAttribute() returns NO_ERROR. If there is an error, WindowChangeBorderAttribute() returns the following value: BAD_WINDOW if the WPOINTER w does not exist. WindowDrawBorder() ------------------ You can also change the border type, or draw a border on an unbordered window by calling the WindowDrawBorder() function. Page 28 The C Window Library Page 28 Here is a prototype: int WindowDrawBorder(WPOINTER w, char *box) The first argument is the window we want to change the border of. The second argument is a string of border characters. This string denotes the type of border that the window should now have. In the example given below, w is initialized with a SINGLEBOX border, but WindowDrawBorder() changes this to a DOUBLEBOX. The WindowDrawBorder() function is also used to draw borders on borderless windows. When drawing borders on a NOBORDER window, the window must not have any of its sides touching the edges of the physical screen. In other words, the window must "have room" for a border to be drawn. If there is no room to draw the border, there is no change to the window. Example: #include "window.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(NOBORDER,2,2,10,10,REVERSE,REVERSE, SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowDrawBorder(w,DOUBLEBOX); /* Draws a double box around NOBORDER window */ } If there is no error, WindowDrawBorder() returns NO_ERROR. If there is an error, WindowDrawBorder() returns one of the following values: BAD_WINDOW if the window w does not exist. NO_HEAP_MEM if there is not enough memory to allocate for temporary buffer. Page 29 The C Window Library Page 29 WindowRemoveBorder() -------------------- This function removes a border from a bordered window. Here is the prototype: int WindowRemoveBorder(WPOINTER w) If the window does not have a border, nothing is changed. Example: #include "window.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,10,10,REVERSE,REVERSE, SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowRemoveBorder(w); /* Removes the double box around BORDERed window */ } If there is no error, WindowRemoveBorder() returns NO_ERROR. If there is an error, WindowRemoveBorder returns one of the following values: BAD_WINDOW if the window w does not exist. NO_HEAP_MEM if there is not enough memory to allocate for temporary buffer. WindowResizeHeight() -------------------- This function changes the inside (text portion) height of the window. Here is a prototype: int WindowResizeHeight(WPOINTER w, int newheight, int anchor) The newheight argument is the new height of the window. If the height will exceed the bounds of the screen, the window is given its maximum height. The anchor argument determines which side to "hold down" while the window is being resized. If the anchor is ANCHORTOP, the top line of the window is held in its current position and the window is resized accordingly. If anchor is ANCHORBOTTOM, the bottom of the Page 30 The C Window Library Page 30 window is held and the window is resized accordingly. If there is text in the window, the text will be truncated if the window is made shorter (unless the window is a viewport to a virtual window. Virtual windows are discussed in the VIRTUAL WINDOWS section). Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowResizeHeight(w,15,ANCHORTOP); /* height now is 15 */ GET_KEY(); WindowResizeHeight(w,5,ANCHORBOTTOM);/* height is now 5 */ } If there were no errors, NO_ERROR is returned. If there is an error, WindowResizeHeight() returns one of the following values: BAD_WINDOW if the WPOINTER w does not exist. NO_HEAP_MEM if there was not enough memory to allocate for the resized window. WindowResizeWidth() ------------------- This function changes the inside (text portion) width of the window. Here is a prototype: int WindowResizeWidth(WPOINTER w, int newwidth, int anchor) The newwidth argument is the new width of the window. If the width will exceed the bounds of the screen, the window is given its maximum width. The anchor argument determines which side to "hold down" while the window is being resized. If the anchor is ANCHORLEFT, the left side of the window is held in its current position and the window is resized Page 31 The C Window Library Page 31 accordingly. If anchor is ANCHORRIGHT, the right side of the window is held and the window is resized accordingly. If there is text in the window, the text will be truncated if the window is made shorter (unless the window is a viewport to a virtual window. Virtual windows are discussed in the VIRTUAL WINDOWS section). main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowResizeWidth(w,15,ANCHORLEFT);/* width is now 15 */ GET_KEY(); WindowResizeWidth(w,5,ANCHORRIGHT);/* width is now 5 */ } If there were no errors, NO_ERROR is returned. If there is an error, WindowResizeWidth() returns one of the following: BAD_WINDOW if the WPOINTER w does not exist. NO_HEAP_MEM if there was not enough memory to allocate for the resized window. Page 32 The C Window Library Page 32 WRITING TEXT TO WINDOWS ----------------------- There are various functions that will write text to a window. These functions are divided into two groups: Functions that specify a null terminated string, and functions that require the length of the string of characters to write to be an explicit argument. Null Terminated Write Functions ------------------------------- WindowWriteString() ------------------- The WindowWriteString() function writes a null terminated string of characters to a window at a specified row and column of the window. If the string is too long to fit in the boundaries of the window, the string is clipped (truncated) to fit in the boundaries of the window. Here is the prototype: int WindowWriteString(WPOINTER w, char *string, int row, int col) The first argument is the window to write the string to. The second argument is the null terminated string to write. The third and fourth arguments are the row and column of the window to place the string. The video attribute used when writing the string is the video attribute of the inside of the window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); for (i=1;i<=10;i++) WindowWriteString(w,"Hello World",i,1); } Page 33 The C Window Library Page 33 The above example writes the string "Hello World" to each line of the window w. If there is no error WindowWriteString() returns NO_ERROR. If there is an error WindowWriteString() returns the following: BAD_WINDOW if the WPOINTER w does not exist. WINDOW_BOUND if the row or column specified are out of bounds of the window. WINDOW_NOT_OPEN if the window was not open for writing (did not use WindowOpen() on the window) WindowWriteStringAttr() ----------------------- The WindowWriteStringAttr() function works the same as the WindowWriteString() function except that an extra argument determines the color used to write the string. Here is the prototype: int WindowWriteStringAttr(WPOINTER w, char *string, int row, int col, int attr) The first argument is the window to write the string to. The second argument is the null terminated string to write. The third and fourth arguments are the row and column of the window to place the string. The last argument is the video attribute to use. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); for (i=1;i<=10;i++) WindowWriteStringAttr(w,"Hello World",i,1,REVERSE); } Page 34 The C Window Library Page 34 The above example writes the string "Hello World" to each line of the window w using the video attribute defined by the constant REVERSE. The return values to WindowWriteStringAttr() are the same as WindowWriteString(). WindowWriteCenterString() ------------------------- The WindowWriteCenterString() function centers a null terminated string in a window. Here is a prototype: int WindowWriteCenterString(WPOINTER w, char *string, int row) The first argument is the window. The second argument is the string to write. The third argument is the row that the string will be centered. The attribute used to write the string is the attribute of the inside of the window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); for (i=1;i<=10;i++) WindowWriteCenterString(w,"Hello World",i); } The above example writes and centers the string "Hello World" to each line of the window w. The return values for WindowWriteCenterString() are the same as WindowWriteString(). Page 35 The C Window Library Page 35 WindowWriteCenterStringAttr() ----------------------------- The WindowWriteCenterStringAttr() function works the same as the WindowWriteCenterString() function except that an extra argument determines the color used to write the string. Here is the prototype: int WindowWriteCenterStringAttr(WPOINTER w, char *string, int row, int attr) The first argument is the window. The second argument is the string to write. The third argument is the row that the string will be centered. The last argument is the video attribute to use to write the string. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); for (i=1;i<=10;i++) WindowWriteCenterStringAttr(w,"Hello World",i,REVERSE); } The above example writes and centers the string "Hello World" to each line of the window w using REVERSE as the video attribute. The return values for WindowWriteCenterStringAttr() are the same as WindowWriteString(). WindowWriteStringCC() --------------------- Centers and writes a string around a column of the window (the CC stands for Centered Column). If the string is longer than the width of the window, the string is placed on column 1 of the window and is clipped at the right edge of the window. Here is the prototype: Page 36 The C Window Library Page 36 The attribute used to write the string is the attribute of the inside of the window. int WindowWriteStringCC(WPOINTER w, char *string, int row) The first argument is the window. The second argument is the string. The third argument is the row to write the string, and the last argument is the column to center the string on. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteStringCC(w,"This",1,10); WindowWriteStringCC(w,"is",2,10); WindowWriteStringCC(w,"centered",3,10); WindowWriteStringCC(w,"around",4,10); WindowWriteStringCC(w,"column",5,10); WindowWriteStringCC(w,"10",6,10); } The example above writes the text centered around column 10 of the window w. The return values for WindowWriteStringCC() are the same as WindowWriteString(). WindowWriteStringCCAttr() ------------------------- The WindowWriteStringCCAttr() function works the same as the WindowWriteStringCC() function except that an extra argument determines the color used to write the string. Here is the prototype: int WindowWriteStringCCAttr(WPOINTER w, char *string, int row, int col, int attr) The first argument is the window. The second argument is the Page 37 The C Window Library Page 37 string to write. The third argument is the row that the string will be centered. The column argument is the column to center the string on. The last argument is the video attribute to use to write the string. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteStringCCAttr(w,"This",1,10,REVERSE); WindowWriteStringCCAttr(w,"is",2,10,REVERSE); WindowWriteStringCCAttr(w,"centered",3,10,REVERSE); WindowWriteStringCCAttr(w,"around",4,10,REVERSE); WindowWriteStringCCAttr(w,"column",5,10,REVERSE); WindowWriteStringCCAttr(w,"10",6,10,REVERSE); } The example above writes the text centered around column 10 of the window w using the video attribute REVERSE. The return values for WindowWriteStringCCAttr() are the same as WindowWriteString(). WindowWriteStringRJ() --------------------- The WindowWriteStringRJ() function writes a right justified string. Here is the prototype: int WindowWriteStringRJ(WPOINTER w, char *string, int row, int col) The first argument is the window. The second argument is the string. The third argument is the row to write the string, and the last argument is the column to place the right edge of the string. Page 38 The C Window Library Page 38 Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteStringRJ(w,"This",1,10); WindowWriteStringRJ(w,"is",2,10); WindowWriteStringRJ(w,"right",3,10); WindowWriteStringRJ(w,"justified",4,10); WindowWriteStringRJ(w,"on ",5,10); WindowWriteStringRJ(w,"column",6,10); WindowWriteStringRJ(w,"10",7,10); } The example above writes the text right justified on column 10 of the window w. The attribute used to write the string is the attribute of the inside of the window. The return values for WindowWriteStringRJ() are the same as WindowWriteString(). WindowWriteStringRJAttr() ------------------------- The WindowWriteStringRJAttr() function works the same as the WindowWriteStringRJ() function except that an extra argument determines the color used to write the string. Here is the prototype: int WindowWriteStringRJAttr(WPOINTER w, char *string, int row, int col, int attr) The first argument is the window. The second argument is the string to write. The third argument is the row to write the string. The col is the column to right justify the string. The last argument is the video attribute to use to write the string. Page 39 The C Window Library Page 39 Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteStringRJAttr(w,"This",1,10,REVERSE); WindowWriteStringRJAttr(w,"is",2,10,REVERSE); WindowWriteStringRJAttr(w,"right",3,10,REVERSE); WindowWriteStringRJAttr(w,"justified",4,10,REVERSE); WindowWriteStringRJAttr(w,"on ",5,10,REVERSE); WindowWriteStringRJAttr(w,"column",6,10,REVERSE); WindowWriteStringRJAttr(w,"10",7,10,REVERSE); } The example above writes the text right justified at column 10 of the window w using the video attribute REVERSE. The return values for WindowWriteStringRJAttr() are the same as WindowWriteString(). Length Controlled Write Functions --------------------------------- The upcoming functions must have the length explicitly stated as one of the arguments. These functions do not stop writing characters if the null character in the string to write is reached. WindowWriteCharacters() ----------------------- This function writes characters from a buffer to the window. Here is the prototype: int WindowWriteCharacters(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second argument is a Page 40 The C Window Library Page 40 pointer to the buffer where the characters are stored. The third and fourth arguments are the (row,col) position in the window to write the string, and the last argument is the number of characters from buffer to write. The attribute used is the attribute of the inside of the window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; char buf[] = "Hello World!!"; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteCharacters(w,buf,1,1,11); WindowWriteCharacters(w,buf,2,1,13); } The return values for WindowWriteCharacters() are the same as WindowWriteString(). WindowWriteAttributes() ----------------------- This function writes attributes from a buffer to the window. Here is the prototype: int WindowWriteAttributes(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second argument is a pointer to the buffer where the attributes are stored. The third and fourth arguments are the (row,col) position in the window to write the string, and the last argument is the number of attributes from buffer to write. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) Page 41 The C Window Library Page 41 WPOINTER w; char buf[13]; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=0;i<13;i++) if (i % 2) buf[i] = NORM; else buf[i] = REVERSE; WindowWriteString(w,"Hello World!!",1,1); GET_KEY(); WindowWriteAttributes(w,buf,1,1,13); /* Writes alternating NORM and REVERSE attributes */ } The return values for WindowWriteAttributes() are the same as WindowWriteString(). WindowWriteCharAndAttr() ------------------------ The WindowWriteCharAndAttr() function writes a string of character/attribute pairs to a window. Use this function if you have created a string of character/attribute pairs, and want to output them easily. The string consists of character and attributes in the following manner: char-attr-char-attr... Each character is followed by its corresponding video attribute. Here is the prototype: int WindowWriteCharAndAttr(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second is the buffer where the character and attributes are stored. The third and Page 42 The C Window Library Page 42 fourth is the (row,col) position in the window to write, and the length argument is the number of character/attribute pairs from the buffer to write. Please note the difference in the meaning of the length argument in this function as opposed to its use in the preceding functions. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; char buf[26]; char *str = "Hello World!!"; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=0;i<26;i+=2,str++) { buf[i] = *str; buf[i+1] = NORM; } WindowWriteCharAndAttr(w,buf,1,1,13); } The return values for WindowWriteCharAndAttr() are the same as WindowWriteString(). WindowWriteCharactersAttr() --------------------------- The WindowWriteCharactersAttr() function writes characters from a buffer to a window. The difference between this function and WindowWriteCharacters() is that a video attribute is specified. Here is the prototype: int WindowWriteCharactersAttr(WPOINTER w, char *buffer, int row, int col, int attr, int length) The attr argument is the video attribute to use when writing the characters. Page 43 The C Window Library Page 43 Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; char buf[] = "Hello World!!"; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteCharactersAttr(w,buf,2,1,REVERSE,13); } The return values for WindowWriteCharactersAttr() are the same as WindowWriteString(). WindowWriteRepeatAttribute() ---------------------------- The WindowWriteRepeatAttribute() function writes an attribute a specified number of times to a window. Here is a prototype: int WindowWriteRepeatAttribute(WPOINTER w, int attr, int row, int col, int count) The attr argument is the attribute to use. The count argument specifies the number of times to write the attribute attr to the window starting at (row,col). Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; main() { WindowInitializeSystem(); Page 44 The C Window Library Page 44 WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Hello World!!",1,1); GET_KEY(); WindowWriteRepeatAttribute(w,REVERSE,1,1,13); } The example above illustrates that the WindowWriteRepeatAttribute() writes the REVERSE attribute 13 times starting at row 1, column 1 of the window w. The return values for WindowWriteRepeatAttribute() are the same as WindowWriteString(). WindowWriteRepeatCharacter() ---------------------------- The WindowWriteRepeatCharacter() function writes a character a specified number of times to a window. Here is a prototype: int WindowWriteRepeatCharacter(WPOINTER w, int ch, int row, int col, int count) The count argument is the character to use. The count argument specifies the number of times to write the character ch to the window starting at (row,col). #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowWriteRepeatCharacter(w,'a',1,1,5); WindowWriteRepeatCharacter(w,'b',2,1,5); WindowWriteRepeatCharacter(w,'c',3,1,5); } The example above illustrates that the WindowWriteRepeatCharacter() writes the letter 'a', 'b', and Page 45 The C Window Library Page 45 'c' 5 times on rows 1, 2, and 3 respectively. The return values for WindowWriteRepeatCharacter() are the same as WindowWriteString(). Formatted Write Functions ------------------------- These functions write formatted output to windows just like the printf() function. There are two functions that do this, namely WindowPrintf() and WindowPrintfAttr(). These functions use a format string that is similar to the format string found in printf(). For example, %d, %s, %lf, etc. and most of the escape sequences are supported. The list of escape sequences supported are as follows: \n - newline \b - backspace \t - tab \a - bell \r - carriage return \x - hexadecimal Where output is placed in the window ------------------------------------ The row and column of where the string will be written is determined by the window's logical cursor. The logical cursor is advanced by both of these functions to one column position after the last character is printed. If you want to start at a particular row and column of the window, you must move the cursor yourself by calling the WindowMoveCursor() function. This function is explained later in the CURSOR POSITIONING IN WINDOWS section. If the window is displayed, the logical cursor of the window is equivalent to the screen cursor. If the output to the window will be obscured by other windows, the screen cursor will also be hidden. When the window is first opened using WindowOpen(), the logical cursor is automatically moved to (1,1) of the window. WindowSetWrap() --------------- With these functions, any text that will exceed the boundaries of the window will be wrapped to the next line. If the output will exceed the last row of the window, the window is automatically scrolled up by one line. This is the default action that is taken when characters exceed the right edge of the window. If you want the output clipped instead of wrapped, you must set the window's wrap flag using the Page 46 The C Window Library Page 46 WindowSetWrap() function. The WindowSetWrap() function sets the window's wrap flag to either on or off. Here is the prototype: int WindowSetWrap(WPOINTER w, int option) The second argument will be 0 if you want to turn the wrap flag off, or 1 if you want to turn it on. If the wrap flag is off, the output generated by WindowPrintf() and WindowPrintfAttr() will be terminated when the right edge of the window is reached. If the wrap flag is on, the output is wrapped to the next line when the right edge is reached, and the window will be scrolled up by one line if the output will exceed the last row. You can set the wrap flag to a window at any time. WindowPrintf() -------------- The WindowPrintf() function writes formatted output to the window. Here is the prototype: int WindowPrintf(WPOINTER w, char *format [,arg1,...]) The first argument is the window. The second argument is a format string. The rest of the arguments are optional arguments that are written to the window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; char *s1 = "This string will wrap around to the next line\n"; char *s2 = "This escape code will ring the bell \a"; int i = 3; double j = 5.6; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowPrintf(w,"3+2 is equal to %d\n",3+2); GET_KEY(); WindowPrintf(w,"i is equal to %d\nj is equal to %lf\n",i,j); GET_KEY(); WindowPrintf(w,s1); GET_KEY(); Page 47 The C Window Library Page 47 WindowPrintf(w,s2); } The above example illustrates how WindowPrintf() is used to print formatted strings. The return values for WindowPrintf() are the same as WindowWriteString(). WindowPrintfAttr() ------------------ The WindowPrintfAttr() function writes formatted output to the window. The difference between WindowPrintf() and WindowPrintfAttr() is that WindowPrintfAttr() uses a video attribute specified as an argument. Here is the prototype: int WindowPrintfAttr(WPOINTER w, int attr, char *format [,arg1,...]) The first argument is the window. The second argument is the video attribute to use. The third argument is the format string. The rest of the arguments are optional arguments that are written to the window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; char *s1 = "This string will wrap around to the next line\n"; char *s2 = "This escape code will ring the bell \a"; int i = 3; double j = 5.6; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowPrintfAttr(w,REVERSE,"3+2 is equal to %d\n",3+2); GET_KEY(); WindowPrintfAttr(w,REVERSE, "i is equal to %d\nj is equal to %lf\n",i,j); GET_KEY(); WindowPrintfAttr(w,REVERSE,s1); GET_KEY(); WindowPrintfAttr(w,REVERSE,s2); } Page 48 The C Window Library Page 48 The above example illustrates how WindowPrintfAttr() is used to print formatted strings. The return values for WindowPrintfAttr() are the same as WindowWriteString(). Page 49 The C Window Library Page 49 WRITING TITLES TO WINDOWS ------------------------- This section only applies to bordered windows. There are two methods of writing text to the top or bottom border of a window. Each method has its advantages and disadvantages. The first method is to explicitly write to the border of the window. Except for the WindowPrintf...() functions, if you specify the row number to be 0, the text is written on the upper border of the window. If the row number is equal to the window height + 1, the text is written on the lower border of the window. To access the window's height use the macro WINDOW_HEIGHT() described later in the WINDOW MACROS section. If you want to write a formatted string on the border of the window, use the standard library function sprintf() to create a string of formatted output, and then write this string with one of the WindowWrite...() functions. Any text that is written on the borders of a window are not retained if the window is resized using one of the WindowResize...() functions, or if the border is changed using WindowDrawBorder(). Therefore it is a good idea to maintain what is on the borders of the window in your own string variables. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); /* Specify row 0 to write on */ WindowWriteCenterString(w,"This is a title",0); WindowWriteCenterString(w,"This is a title", WINDOW_HEIGHT(w) + 1); } Page 50 The C Window Library Page 50 The second method is writing a string of text to either the top or bottom border by using the WindowTitle...() functions. The advantage of using these functions is that the strings are retained automatically if the window is resized or the border type is changed. Another advantage is that if the title does not fit in the boundaries of the window, the title is truncated, but the full title is retained in a buffer. If the window is later resized so that the title can fit, the full title will appear on the border. The disadvantage is that only one string of text is allowed for the top and bottom borders, and there are only three positions on each border to place the title. WindowTitleTop() ---------------- The WindowTitleTop() function writes a title to the top border of a window. Here is the prototype: int WindowTitleTop(WPOINTER w, char *title, int pos) The first argument is the window to write the title. The second argument is the title to write. The third argument is the position to place the title. Here is a list of valid constants to use for the position: TITLELEFT - Places the title starting at column 1 of the window. TITLECENTER - Centers the title in the window. TITLERIGHT - Right justifies the title to the last column of the window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); /* left justify title */ Page 51 The C Window Library Page 51 WindowTitleTop(w,"This is a title",TITLELEFT); GET_KEY(); /* center title */ WindowTitleTop(w,"This is a title",TITLECENTER); GET_KEY(); /* right justify title */ WindowTitleTop(w,"This is a title",TITLERIGHT); } If there are no errors, WindowTitleTop() returns NO_ERROR. If there are errors, WindowTitleTop() returns one of the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen()) WindowTitleBottom() ------------------- The WindowTitleBottom() function writes a title to the bottom border of a window. Here is the prototype: int WindowTitleBottom(WPOINTER w, char *title, int pos) The first argument is the window to write the title. The second argument is the title to write. The third argument is a constant that denotes the position to place the title. A list of valid constants can be found in the description of WindowTitleBottom() described above. #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); /* left justify title */ WindowTitleBottom(w,"This is a title",TITLELEFT); GET_KEY(); Page 52 The C Window Library Page 52 /* center title */ WindowTitleBottom(w,"This is a title",TITLECENTER); GET_KEY(); /* right justify title */ WindowTitleBottom(w,"This is a title",TITLERIGHT); } If there are no errors, WindowTitleBottom() returns NO_ERROR. If there are errors, WindowTitleBottom() returns one of the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen()) WindowTitleTopAttr() -------------------- The WindowTitleTopAttr() function writes a title to the top border of a window with a specified color attribute. Here is the prototype: int WindowTitleTopAttr(WPOINTER w, char *title, int pos, int attr) The first argument is the window to write the title. The second argument is the title to write. The third argument is a constant that denotes the position to place the title. A list of valid constants can be found in the description of WindowTitleTopAttr() described above. The fourth argument is the color attribute to use. #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); Page 53 The C Window Library Page 53 /* left justify title */ WindowTitleTopAttr(w,"This is a title",TITLELEFT,REVERSE); GET_KEY(); /* center title */ WindowTitleTopAttr(w,"This is a title",TITLECENTER,REVERSE); GET_KEY(); /* right justify title */ WindowTitleTopAttr(w,"This is a title",TITLERIGHT,REVERSE); } If there are no errors, WindowTitleTopAttr() returns NO_ERROR. If there are errors, WindowTitleTopAttr() returns one of the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen()) WindowTitleBottomAttr() ----------------------- The WindowTitleBottomAttr() function writes a title to the bottom border of a window with a specified color attribute. Here is the prototype: int WindowTitleBottomAttr(WPOINTER w, char *title, int pos, int attr) The first argument is the window to write the title. The second argument is the title to write. The third argument is a constant that denotes the position to place the title. A list of valid constants can be found in the description of WindowTitleBottomAttr() described above. The fourth argument is the color attribute to use. #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); Page 54 The C Window Library Page 54 WindowDisplay(w,1,NOEFFECT); GET_KEY(); /* left justify title */ WindowTitleBottomAttr(w,"This is a title",TITLELEFT, REVERSE); GET_KEY(); /* center title */ WindowTitleBottomAttr(w,"This is a title",TITLECENTER, REVERSE); GET_KEY(); /* right justify title */ WindowTitleBottomAttr(w,"This is a title",TITLERIGHT, REVERSE); } If there are no errors, WindowTitleBottomAttr() returns NO_ERROR. If there are errors, WindowTitleBottomAttr() returns one of the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen()) Page 55 The C Window Library Page 55 READING CHARACTERS AND ATTRIBUTES FROM WINDOWS ---------------------------------------------- With The C Window Library, you can read the contents of a window into a character buffer. These functions provide the programmer with the contents of the window at any time. The functions to perform this are WindowReadAttributes(), WindowReadCharacters(), and WindowReadCharAndAttr(). WindowReadCharacters() ---------------------- The WindowReadCharacters() function reads the characters from a window into a buffer. Here is the prototype. int WindowReadCharacters(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second argument is the buffer to store the characters in. The third and fourth arguments are the (row,col) position in the window to start reading from. The last argument is the number of characters to read. You must make sure that buffer has enough room to hold all of the characters read in. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; char buf[14] = {0}; /* Null all elements of buf */ main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Hello World!!",1,1);/* Write String */ WindowReadCharacters(w,buf,1,1,13); /* Read characters */ GET_KEY(); WindowWriteString(w,buf,2,1); /* Write what we have read */ } The example above illustrates the use of WindowReadCharacters(), which reads the window's contents Page 56 The C Window Library Page 56 starting at (1,1) of the window. This happens to be the string "Hello World!!". After GET_KEY() is called, the results of the buffer are written on line 2 of the window. If the length exceeds the right edge of the window, WindowReadCharacters() will read up to the right edge of the window. If there are no errors, WindowReadCharacters() returns NO_ERROR. If there are errors, WindowReadCharacters() returns one of the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window was not open for reading (use WindowOpen()) WINDOW_BOUND if the row or column specified in the window is out of bounds. WindowReadAttributes() ---------------------- The WindowReadAttributes() function reads the attributes from a window into a buffer. Here is the prototype. int WindowReadAttributes(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second argument is the buffer to store the attributes in. The third and fourth arguments are the (row,col) position in the window to start reading from. The last argument is the number of attributes to read. You must make sure that buffer has enough room to hold all of the attributes read in. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; char buf[14] = {0}; /* Null all elements of buf */ main() { int i; WindowInitializeSystem(); Page 57 The C Window Library Page 57 WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Hello World!!",1,1);/* Write String */ WindowReadAttributes(w,buf,1,1,13); /* Read attributes */ GET_KEY(); WindowWriteString(w,buf,2,1); /* Write what we have read */ } The example above illustrates the use of WindowReadAttributes(), which reads the window's attribute contents starting at (1,1) of the window. This happens to be the attributes of the string "Hello World!!", which is the NORM attribute. After GET_KEY() is called, the results of the buffer are written on line 2 of the window. If the length exceeds the right edge of the window, WindowReadAttributes() will read up to the right edge of the window. If there are no errors, WindowReadAttributes() returns NO_ERROR. If there are errors, WindowReadAttributes() returns one of the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window was not open for reading (use WindowOpen()) WINDOW_BOUND if the row or column specified in the window is out of bounds. WindowReadCharAndAttr() ---------------------- The WindowReadCharAndAttr() function reads character/attribute pairs from a window into a buffer. Here is the prototype. int WindowReadCharAndAttr(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second argument is the buffer to store the character/attribute pairs in. The third and fourth arguments are the (row,col) position in the window to start reading from. The last argument is the number of character/attribute pairs to read. Page 58 The C Window Library Page 58 You must make sure that buffer has enough room to hold all of the character/attribute pairs read in. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; char buf[27] = {0}; /* Null all elements of buf */ main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Hello World!!",1,1);/* Write String */ WindowReadCharAndAttr(w,buf,1,1,13); GET_KEY(); WindowWriteCharAndAttr(w,buf,2,1,13); /* Write what we have read */ } The example above illustrates the use of WindowReadCharAndAttr(), which reads the window's character/attribute contents starting at (1,1) of the window. This happens to be the characters/attributes of the string "Hello World!!". After GET_KEY() is called, the results of the buffer are written on line 2 of the window. If the length exceeds the right edge of the window, WindowReadCharAndAttr() will read up to the right edge of the window. If there are no errors, WindowReadCharAndAttr() returns NO_ERROR. If there are errors, WindowReadCharAndAttr() returns one of the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window was not open for reading (use WindowOpen()) WINDOW_BOUND if the row or column specified in the window is out of bounds. Page 59 The C Window Library Page 59 HIDING WINDOWS -------------- With The C Window Library, you can hide windows at any time without disturbing the contents of other windows. WindowHide() ------------ The WindowHide() function hides a window on the screen from view. The window retains all text and shadows that may be present. Here is a prototype: int WindowHide(WPOINTER w, int effect) The first argument is the window, and the last argument is the special effect to use when hiding the window. For a list of special effects, refer to the DISPLAYING WINDOWS section. Example : #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white) #define BLACKONWHITE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w1,w2,w3; main() { WindowInitializeSystem(); WindowSaveInitial(0); /* Initialize all windows */ w1 = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); w2 = WindowInitialize(BORDER,2,2,20,10,REDONWHITE,NORM, DOUBLEBOX); w3 = WindowInitialize(BORDER,3,3,20,10,BLACKONWHITE,NORM, SINGLEBOX); /* Open all windows */ WindowOpen(w1); WindowOpen(w2); WindowOpen(w3); /* Display All windows */ WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); WindowDisplay(w3,3,NOEFFECT); WindowWriteString(w1,"This is window 1",1,1); Page 60 The C Window Library Page 60 WindowWriteString(w2,"This is window 2",2,1); WindowWriteString(w3,"This is window 3",3,1); GET_KEY(); WindowHide(w3,NOEFFECT); GET_KEY(); WindowHide(w2,BRICKS); GET_KEY(); WindowHide(w1,CONTRACT); } The example initializes, opens, and displays three windows. Note that you can hide windows regardless of the order in which they were displayed. This makes for very flexible window management. If there is no error, WindowHide() returns NO_ERROR. The only error that can occur is if the WPOINTER w does not exist. WindowHide() returns BAD_WINDOW if this is the case. Page 61 The C Window Library Page 61 CREATING COPIES OF A WINDOW --------------------------- You can create copies of a window without going through the WindowInitialize(), WindowOpen(), etc. cycle. WindowCopy() ------------ The WindowCopy() function makes a copy of a previous window. The copy will have the same colors, border type, shadow, and may have the same text as a previous window. If the original window is a viewport on a virtual window (virtual windows are discussed later in the VIRTUAL WINDOWS section), the copy can also be made a viewport on the same virtual window. The only thing that will not be copied is the (row,col) of the original window. You supply the position of the new window. Here is the prototype: WPOINTER WindowCopy(WPOINTER w, int row, int col, int options) Please note that WindowCopy() returns a new WPOINTER. You must assign the return value to a WPOINTER or you will not get easy access to the newly created window. The first argument is the original window to copy. This window must already exist. The second and third arguments are the coordinates of where to place the new window. The last argument are additional options that control whether the window will contain the same text as the previous window, and if the new window will be made a viewport if the original window is a viewport. The constants used for options is as follows: options action ------- ------ COPYTEXT Makes a copy of the text area of the original window. MAKEVIEWPORT Turns the copy into a viewport if the original is a viewport. NO_OPTIONS No options desired. As was stated before, viewports are discussed in the VIRTUAL WINDOW section of the manual. If options is NO_OPTIONS, the windows size, border type, shadow (if there is a shadow) and colors are copied. Page 62 The C Window Library Page 62 Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w,w2; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,45,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w, "This will be copied to the new window",1,1); GET_KEY(); w2 = WindowCopy(w,3,3,COPYTEXT); /* Make a copy of w */ WindowDisplay(w2,1,NOEFFECT); /* Display this copy */ GETKEY(); WindowFreeAll(0,NOEFFECT); } If there is no error, WindowCopy() returns a valid WPOINTER. If there is an error, WindowCopy() returns a WIN_NULL_PTR (a null window pointer) and sets window_error_code to one of the following values: NO_HEAP_MEM if there is not enough memory to allocate for the window structure. BAD_WINDOW_SIZE if the dimensions for the window are too large for the physical screen. MAX_WINDOW if there are > 254 windows defined. Page 63 The C Window Library Page 63 SCROLLING TEXT IN WINDOWS ------------------------- With The C Window Library, you can scroll text in a window up, or down, or scroll just particular regions of a window. The functions used to scroll windows are WindowScroll(), WindowScrollAttr(), WindowScrollRegion(), and WindowScrollRegionAttr(). When specifying a direction, use the constant UP to scroll up or DOWN to scroll down. These constants are defined in window.h. WindowScroll() -------------- If you want to scroll the entire window either up or down, you can use the WindowScroll() function. Here is a prototype: int WindowScroll(WPOINTER w, int numlines, int direction) The first argument is the window to scroll. The second argument is the number of lines to scroll. The last argument is the direction to scroll the window (either UP or DOWN). Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20); GET_KEY(); WindowScroll(w,1,UP); GET_KEY(); WindowScroll(w,3,DOWN); } The above example creates text using WindowWriteRepeatCharacter() function. The WindowScroll() Page 64 The C Window Library Page 64 calls will scroll the window up by one line, and then scroll the window down by 3 lines. If there is no error, WindowScroll() returns NO_ERROR. If there is an error, WindowScroll() will return the following values: BAD_WINDOW if the WPOINTER w does not exist. WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen() to open the window for writing). WindowScrollRegion() -------------------- The WindowScrollRegion() functions scrolls a specified region of a window. To use the WindowScrollRegion() function, you must describe the rectangular region to scroll. Here is the prototype: int WindowScrollRegion(WPOINTER w, int numlines, int urow, int ucol, int lrow, int lcol, int direction) Arguments 3 thru 6 describe the rectangular region. They are in the order of upper left row, upper left column, lower right row, lower right column. All of these coordinates are window relative. The second argument is the number of lines to scroll. The last argument is the direction. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20); GET_KEY(); WindowScrollRegion(w,1,2,2,4,10,UP); GET_KEY(); WindowScrollRegion(w,3,7,2,9,8,DOWN); } Page 65 The C Window Library Page 65 The above example creates text using WindowWriteRepeatCharacter() function. The first WindowScrollRegion() call will scroll the region described by the rectangular coordinates (2,2) and (4,10). This region is scrolled up one line. The second call to WindowScrollRegion() scrolls the region defined by the rectangular region (7,2) and (9,8). This region is scrolled down by three lines. If there is no error, WindowScrollRegion() returns NO_ERROR. If there is an error, the WindowScrollRegion() function will return of the following values: BAD_WINDOW if the WPOINTER w does not exist. WINDOW_BOUND if the rectangular region defined is out of bounds of the window. WINDOW_NOT_OPEN if the window was not open for writing (use WindowOpen() to open the window for writing). WindowScrollAttr() ------------------ This function works the same way as the WindowScroll() function except that an attribute is defined for the blank lines that are created when the window is scrolled. Here is a prototype: int WindowScrollAttr(WPOINTER w, int numlines, int direction, int attr) The last argument is the attribute to use for the blank lines created. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); Page 66 The C Window Library Page 66 for (i=0;i<10;i++) WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20); GET_KEY(); WindowScrollAttr(w,1,UP,REDONWHITE); GET_KEY(); WindowScrollAttr(w,3,DOWN,REDONWHITE); } The above example creates text using WindowWriteRepeatCharacter() function. The WindowScrollAttr() calls will scroll the window up by one line, and then scroll the window down by 3 lines with both scrolls using REDONWHITE as the video attribute. WindowScrollAttr() returns the same values as WindowScroll(). WindowScrollRegionAttr() ------------------------ This function works the same way as the WindowScrollRegion() function except that an attribute is defined for the blank lines that are created when the window is scrolled. Here is a prototype: int WindowScrollRegionAttr(WPOINTER w, int numlines, int int urow, int ucol, int lrow, int lcol, int direction, int attr) The last argument is the attribute to use for the blank lines created. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteRepeatCharacter(w,'A'+i,i+1,1,20); GET_KEY(); WindowScrollRegionAttr(w,1,3,5,6,15,UP,REDONWHITE); Page 67 The C Window Library Page 67 GET_KEY(); WindowScrollRegionAttr(w,3,8,4,10,12,DOWN,REDONWHITE); } The above example creates text using WindowWriteRepeatCharacter() function. The first WindowScrollRegionAttr() call will scroll the region described by the rectangular coordinates (2,2) and (4,10). This region is scrolled one line. The second call to WindowScrollRegionAttr() scrolls the region defined by the rectangular region (7,2) and (9,8). This region is scrolled down by three lines. All blank lines use the video attribute REDONWHITE. WindowScrollRegionAttr() returns the same values as WindowScrollRegion(). Page 68 The C Window Library Page 68 CLEARING WINDOWS ---------------- The C Window Library contains functions that clears the entire window, or clears defined rectangular regions of the window. WindowClear() ------------- The WindowClear() function clears an entire window to spaces. The attribute used is the current attribute of the text area of the window. Here is the prototype: int WindowClear(WPOINTER w) The only argument is the window to clear. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=1;i<=10;i++) WindowWriteString(w,"Hello World!!",i,1); GET_KEY(); WindowClear(w); } If there is no error, WindowClear() returns NO_ERROR. If there is an error, WindowClear() returns the following values: BAD_WINDOW if the WPOINTER w does not exist. WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen() to open the window for writing). Page 69 The C Window Library Page 69 WindowClearAttr() ----------------- The WindowClearAttr() function works the same way as the WindowClear() function except that an attribute is specified. Here is the prototype: int WindowClearAttr(WPOINTER w, int attr) The second argument is the video attribute to use. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=1;i<=10;i++) WindowWriteString(w,"Hello World!!",i,1); GET_KEY(); WindowClearAttr(w,REDONWHITE); } The return values for WindowClearAttr() are the same as WindowClear(). WindowClearRegion() ------------------- The WindowClearRegion() function clears a region of a window. To use the WindowClearRegion() function, you must describe the rectangular region to clear. Here is the prototype: int WindowClearRegion(WPOINTER w, int urow, int ucol, int lrow, int lcol) where (urow,ucol) describes the upper left of the rectangle and (lrow,lcol) is the lower right of the window. These coordinates are window relative. Page 70 The C Window Library Page 70 Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=1;i<=10;i++) WindowWriteString(w,"Hello World!!",i,1); GET_KEY(); WindowClearRegion(w,4,4,8,15); } The WindowClearRegion() call will clear the region described by the rectangular coordinates (4,4) and (8,15). If there is no error, WindowClearRegion() returns NO_ERROR. If there is an error, the WindowClearRegion() function will return the following values: BAD_WINDOW if the WPOINTER w does not exist. WINDOW_BOUND if the rectangular region defined is out of bounds of the window. WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen() to open the window for writing). WindowClearRegionAttr() ----------------------- The WindowClearRegionAttr() function works the same as the WindowClearRegion() function, except that a video attribute is specified. Here is the prototype: int WindowClearRegionAttr(WPOINTER w, int urow, int ucol, int lrow, int lcol, int attr) The attr argument is a video attribute to use to clear the region. Page 71 The C Window Library Page 71 Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REDONWHITE CREATE_VIDEO_ATTRIBUTE(red,white) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=1;i<=10;i++) WindowWriteString(w,"Hello World!!",i,1); GET_KEY(); WindowClearRegionAttr(w,4,4,8,15,REDONWHITE); } The WindowClearRegionAttr() call will clear the region described by the rectangular coordinates (4,4) and (8,15) using the video attribute defined by the constant REDONWHITE. The WindowClearRegionAttr() returns the same values as WindowClearRegion(). Page 72 The C Window Library Page 72 WRITING WINDOW CONTENTS TO A FILE --------------------------------- The C Window Library allows you to print the contents of a window using the WindowWriteTextToFile() function. WindowWriteTextToFile() ----------------------- The WindowWriteTextToFile() function allows you to print the contents of a window to a file. Here is the prototype: int WindowWriteTextToFile(WPOINTER w, char *filename, int mode) The first argument is the window. The second argument is the file name. This file can be any of the DOS filenames ("con", "prn", "aux", etc.). The file specified by filename must be closed before calling WindowWriteTextToFile(), and the file handle is automatically closed before exiting WindowWriteTextToFile(). The last argument is the mode switch. If mode is 1, a newline ('\n') is written to the file after each line of the window is written to the file. If mode is 0, no newline character is written. Example: #include "window.h" #include <stdio.h> #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; FILE *outfile; char *filename = "wintext"; char *filename2 = "wintext2"; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=1;i<=10;i++) WindowWriteString(w,"Hello World!!",i,1); GET_KEY(); WindowWriteTextToFile(w,filename,1); /* use newlines */ WindowWriteTextToFile(w,filename2,0); /* no newlines */ } Page 73 The C Window Library Page 73 The example above illustrates two calls to WindowWriteTextToFile(). The first call writes the contents of the window w to a file called "wintext". Note that the mode parameter for the first call is 1. This will cause '\n' to be written to the file for each line of the window. The second call writes the window text to a file call "wintest2", with the mode parameter being 0 (no '\n'). Please note that WindowWriteTextToFile() does not check if the file already exists, so be careful that you do not replace files that are important to you. If there are no errors, WindowWriteTextToFile() returns NO_ERROR. If there are errors, WindowWriteTextToFile() will return one of the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen()) FILE_CANT_OPEN if the file specified by filename cannot be open. FILE_CANT_CLOSE if the file specified by filename cannot be closed. Page 74 The C Window Library Page 74 SHADOWING WINDOWS ----------------- With The C Window Library, you can place shadows on the windows created. Shadows create a nice effect when displayed with the proper background color. There are four positions where you can place a shadow on a window: the upper left corner of the window, the upper right corner, the lower left corner or the lower right corner. The shadow consists of two components. One of these components is the part of the shadow that is drawn either on the left or right side of the window. You can control the width of this portion of the shadow. The other component that makes up the shadow is the portion that is drawn either on top of or underneath a window. You can control the height of this portion of the shadow. You can also control the shadows video attribute, as well as the character that makes up the shadow itself. My suggestion is to use ASCII character 219 for the shadow character. Other ones that work well are ASCII 176, 178, and 178. Transparent shadows are also supported. You can place a shadow on a window at any time or take it off at any time. The only restriction with the shadow is that the window's current position must have room to draw the shadow. WindowDrawShadow() ------------------ The WindowDrawShadow() function places a shadow on a window. Here is the prototype: int WindowDrawShadow(WPOINTER w, int shadowpos, int width, int height, int shadowchar, int shadowattr, int transflag) The first argument is the window that the shadow will be drawn. The second argument is the position of the shadow. There are four possible positions: SHADOWUPRIGHT - draws shadow on upper right corner of the window. SHADOWUPLEFT - draws shadow on upper left corner of the window. SHADOWLOWRIGHT - draws shadow on lower right corner of window. SHADOWLOWLEFT - draws shadow on lower left corner of window. Page 75 The C Window Library Page 75 The third argument is the width of the strip of the shadow that is drawn on the right or left side of the window. The fourth argument is the height of the strip of the shadow that is drawn on top or underneath the window. The fifth argument is the character to use for the shadow. The sixth argument is the attribute to use for the shadow. The last argument is a flag denoting whether the shadow should be a transparent shadow. If the flag is 0, the shadow is solid, otherwise the shadow is transparent. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) #define REDONBLACK CREATE_VIDEO_ATTRIBUTE(black,red) #define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(black,green) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) main() { WPOINTER w0,w1; WindowInitializeSystem(); WindowSaveInitial(0); w0 = WindowInitialize(NOBORDER,1,1,80,25,REVERSE,REVERSE,0); WindowOpen(w0); WindowDisplay(w0,1,NOEFFECT); w1 = WindowInitialize(BORDER,5,5,40,15,BLUEONBLACK, REDONBLACK,SINGLEBOX); WindowOpen(w1); WindowDrawShadow(w1,SHADOWUPLEFT,2,1,219,REVERSE,0); WindowDisplay(w1,1,NOEFFECT); WindowWriteString(w1,"Press a key to move shadow",1,1); GET_KEY(); WindowDrawShadow(w1,SHADOWUPRIGHT,2,1,219,REVERSE,0); WindowWriteString(w1,"Press a key again",2,1); GET_KEY(); WindowDrawShadow(w1,SHADOWLOWLEFT,2,1,219,REVERSE,0); WindowWriteString(w1,"Press a key once more",3,1); GET_KEY(); WindowDrawShadow(w1,SHADOWLOWRIGHT,2,1,219,REVERSE,0); GET_KEY(); WindowClose(w1,NOEFFECT); WindowClose(w0,NOEFFECT); } The above example illustrates the use of WindowDrawShadow(). If there is no error, WindowDrawShadow() returns NO_ERROR. If there are errors, WindowDrawShadow() returns one of the following: BAD_WINDOW if the window does not exist. Page 76 The C Window Library Page 76 WINDOW_BOUND if a shadow could not be drawn because of window location and the height and/or width of the shadow will exceed the screen edges. WindowRemoveShadow() -------------------- The WindowRemoveShadow() function removes a shadow from a window, and takes a single argument, namely the window pointer. Here is the prototype: int WindowRemoveShadow(WPOINTER w) If there are no errors or the window does not have a shadow, WindowRemoveShadow() returns NO_ERROR. If there are errors, WindowRemoveShadow() returns the following value: BAD_WINDOW if the window does not exist. Page 77 The C Window Library Page 77 SEE-THRU WINDOWS ---------------- You can create windows that have borders, but do not overwrite the screen underneath. These windows are called see-thru windows. When creating see-thru windows the WindowMakeSeeThru() function is used to make a defined window a see-thru window. You can turn a non-seethru window into a seethru window and vice-versa by calling the WindowMakeNormal() function. WindowMakeSeeThru() ------------------- The WindowMakeSeeThru() function turns a normal window into a see-thru window. Here is a prototype: int WindowMakeSeeThru(WPOINTER w) The only argument is the window pointer. You can make a window a see-thru window at any time, including if it is hidden. If there is text in the normal window before making it a see-thru window, the text is retained. If text is written to a see-thru window, the text is written to the window's internal write buffer, but is not displayed on the screen. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,5,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowMakeSeeThru(w); GET_KEY(); WindowFree(w,NOEFFECT); } The example above displays a normal window, and then turns Page 78 The C Window Library Page 78 the normal window into a see-thru window when a key is pressed. If there are no errors, WindowMakeSeeThru() returns NO_ERROR. If there are errors, WindowMakeSeeThru() returns the following value: BAD_WINDOW if the window does not exist. WindowMakeNormal() ------------------ The WindowMakeNormal() function turns a see-thru window into a normal text window. Any text that may have been written to the window will be displayed. Here is the prototype: int WindowMakeNormal(WPOINTER w) Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,5,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowMakeSeeThru(w); GET_KEY(); WindowMakeNormal(w); } The example above demonstrates the WindowMakeNormal() function. If there are no errors, WindowMakeNormal() returns NO_ERROR. If there are errors, WindowMakeNormal() returns the following value: BAD_WINDOW if the window does not exist. Page 79 The C Window Library Page 79 MOVING AND SLIDING WINDOWS -------------------------- With The C Window Library, you can move and slide windows on the screen. The functions that perform this are the WindowMove() and WindowSlide(). WindowMove() ------------ The WindowMove() function moves a window to a new location on the screen. Here is the prototype: int WindowMove(WPOINTER w, int row, int col) The first argument is the window. The second and third arguments are the row and column on the physical screen to place the upper left hand corner of the window. Note that row and column are screen relative coordinates, not window relative. This is one of the few functions where row and column denote a screen relative coordinate and not a window relative coordinate. If the row and/or column is out of bounds, the window is moved as far as possible. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) main() { WPOINTER w; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,15,BLUEONBLACK,NORM, SINGLEBOX); WindowOpen(w); WindowWriteString(w,"Press a key to move me",1,1); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowMove(w,12,14); } The example above moves the window from its original position (1,1) to (12,14). If there is no error WindowMove() returns NO_ERROR. If there are errors WindowMove() returns the following value: BAD_WINDOW if the window does not exist. Page 80 The C Window Library Page 80 WindowSlide() ------------- The WindowSlide() function "slides" a window from one position on the screen to another. Here is the prototype: int WindowSlide(WPOINTER w, int direction, int units) The first argument is the window. The second argument tells in which direction to move the window, either up, down, left, or right. The constants to use for up, down, left, and right are UP, DOWN, LEFT, and RIGHT, respectively. The third argument tells how many rows or columns to move the window. If the number of units will cause the window to exceed the boundaries of the screen, the window is moved as far as possible. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(black,blue) main() { WPOINTER w; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,BLUEONBLACK,NORM, SINGLEBOX); WindowOpen(w); WindowWriteString(w,"Press a key to slide right",1,1); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowSlide(w,RIGHT,20); WindowWriteString(w,"Press a key to slide down",2,1); GET_KEY(); WindowSlide(w,DOWN,10); WindowWriteString(w,"Press a key to slide left",3,1); GET_KEY(); WindowSlide(w,LEFT,20); WindowWriteString(w,"Press a key to slide up",4,1); GET_KEY(); WindowSlide(w,UP,20); } The example above illustrates how to use the WindowSlide() function. The return values for WindowSlide() are the same as WindowMove(). Page 81 The C Window Library Page 81 CURSOR POSITIONING IN WINDOWS ----------------------------- You can change the position of the cursor and its shape in the windows you create with The C Window Library. Cursor Maintenance in The C Window Library ------------------------------------------ As was stated before, The C Window Library can write to any window at any time. This makes the question "which window owns the cursor?" a hard question to answer. One method is that the window being updated either by writing text, clearing, etc. should have immediate control of the cursor. The approach The C Window Library has taken is that the top-most window always has control of the cursor. The topmost window is determined by its rank number. Windows with low rank numbers overlay windows with higher rank numbers. Creating Cursor Shapes ---------------------- The C Window Library has three pre-defined cursor shapes; INVISIBLE, THIN, and BLOCK. An INVISIBLE cursor hides the cursor, a BLOCK shape creates a "fat" cursor, and THIN creates a thin cursor. If you want to define your own cursor shapes, use the CREATE_CURSOR_SHAPE() macro. This macro takes two arguments the first argument is the beginning scan line, and the second argument is the ending scan line. Scan lines determine the height of the cursor. For monochrome systems, the scan lines range from 0 to 13. In a color system, the scan lines range from 0 to 7. A THIN cursor has its starting scan line at 6 and its ending scan line at 7 for color systems, and for monochrome systems, the starting scan line is 11 and its ending scan line is at 12. If the starting scan line number is greater than the ending scan line number, the cursor takes on a 'double' cursor shape. Experiment with different starting and ending scan lines for the desired effect. WindowChangeCursor() -------------------- The WindowChangeCursor() function changes the shape of the cursor in a window. Here is the prototype: int WindowChangeCursor(WPOINTER w, int shape) Page 82 The C Window Library Page 82 The first argument is the window. The second argument is the desired cursor shape. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Press a key to change cursor",1,1); GET_KEY(); WindowChangeCursor(w,BLOCK); WindowWriteString(w,"Press a key to change cursor again", 2,1); GET_KEY(); WindowChangeCursor(w,INVISIBLE); WindowWriteString(w,"Press a key to change cursor again", 3,1); GET_KEY(); WindowChangeCursor(w,THIN); } If there are no errors, WindowChangeCursor() returns NO_ERROR. If there are errors, WindowChangeCursor() returns the following value: BAD_WINDOW if the window does not exist. WindowMoveCursor() ------------------ The WindowMoveCursor() functions moves the cursor in a window to a new location in the window. Here is the prototype: int WindowMoveCursor(WPOINTER w, int row, int col) Page 83 The C Window Library Page 83 The first argument is the window, and the second and third arguments are the new (row,col) position in the window to place the cursor. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Press a key to move cursor",1,1); GET_KEY(); WindowMoveCursor(w,7,5); } If there are no errors, WindowMoveCursor() returns NO_ERROR. If there are errors, WindowMoveCursor() returns the following values: BAD_WINDOW if the window does not exist. WINDOW_BOUND if either new row or column number is out of the boundaries of the window. WindowGetCursorShape() ---------------------- The WindowGetCursorShape() function returns the starting and ending scan lines of the cursor defined in a window. Here is the prototype: int WindowGetCursorShape(WPOINTER w, int *startline, int *endline) The startline and endline arguments are pointers to integers that will contain the starting and ending scan lines of the cursor when WindowGetCursorShape() returns. Page 84 The C Window Library Page 84 Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { int startline,endline; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowGetCursorShape(w,&startline,&endline); WindowPrintf(w, "The starting scan line is %d\nThe ending scan line is %d", startline,endline); } The example above calls WindowGetCursorShape() and uses WindowPrintf() to print what the starting and ending scan lines are. If there are no errors, WindowGetCursorShape() returns NO_ERROR. If there are errors, WindowGetCursorShape() returns the following values: BAD_WINDOW if the window does not exist. WindowGetCursorPosition() ------------------------- The WindowGetCursorPosition() function gives the current row and column of the cursor in a window. Here is the prototype: int WindowGetCursorPosition(WPOINTER w, int *row, int *col) The row and col arguments are pointers to integers that will contain the row and column of the cursor after WindowGetCursorPosition() is called. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) Page 85 The C Window Library Page 85 WPOINTER w; main() { int row,col; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowMoveCursor(w,7,4); WindowGetCursorPosition(w,&row,&col); WindowPrintf(w, "The row of the cursor is %d\n" "The column of the cursor is %d", row,col); } If there are no errors, WindowGetCursorPosition() returns NO_ERROR. If there are errors, WindowGetCursorPosition() returns the following value: BAD_WINDOW if the window does not exist. Page 86 The C Window Library Page 86 GETTING WHICH WINDOW OCCUPIES A LOCATION ---------------------------------------- You can determine the WPOINTER which occupies a location on the screen. If you have multiple windows displayed, this can be very useful if you have overlaps and want to know which window is visible in a given screen location. WindowWhich() ------------- The WindowWhich() function determines which window is visible on a given screen location. Here is the prototype: WPOINTER WindowWhich(int row, int col, int page) Note that WindowWhich() returns a WPOINTER. The arguments row and col are absolute screen coordinates. The last argument, page, is the video page to use when determining which window lies in position (row,col). The WPOINTER that is returned is the WPOINTER that occupies the specified screen location. #include "window.h" WPOINTER w1, w2, w3, w4, w5; main() { /* ... Assume everything including windows have been initialized and opened */ if (WindowWhich(4,7,0) == w1) { /* some part of w1 is visible on row 4 column 7 of the screen (video page 0) */ } } The above example calls WindowWhich to determine if w1 is visible on position (4,7) of video page 0. Refer to the INTRODUCTION on video pages. If there is no window visible for a given screen location, WIN_NULL_PTR is returned. The base screen will always return a WIN_NULL_PTR. Page 87 The C Window Library Page 87 GETTING INPUT FROM WINDOWS -------------------------- With The C Window Library, you can read input from windows. The input can be simple string input, or inputting strings with a character mask. There is also support for scrolling input fields. Input Manager ------------- The input manager are functions internal in The C Window Library that control editing, checking for invalid characters, cursor movement, etc. Regular Expressions ------------------- With The C Window Library, you specify exactly what characters are to be expected for every input position by using a special string of characters called a regular expression (a pattern matching string). Note: For those who are familiar with regular expressions, there is a difference between the regular expressions you will see here, and the regular expressions you will find in certain text editors, or in computer language syntax definitions. One major difference is that there are no wild cards denoting an arbitrary number of repeated characters (which is usually denoted by a '*' or a '+'), and there are no 'match begin of string' and 'match end of string' functions. An example of a regular expression would be the string "[A-Z]" which means only those characters that are between A and Z, inclusive, are to be accepted as valid input characters. Of course, the ASCII collating sequence is used. The following characters have special meanings in regular expressions: Character Purpose --------- ------- Forward Slash (/) Removes the special meaning of the next character in the regular expression. Page 88 The C Window Library Page 88 Brackets ([]) Encloses a set of characters to be matched with the current character entered at the keyboard. There are other special symbols that can appear in brackets: ----------------------------------- Carat (^) This symbol states that the character entered at the keyboard must not match any character in the brackets. The carat must be the first character after the left bracket ([), otherwise the carat is taken literally as just another character. Dash (-) Matches character entered at keyboard with characters in ASCII order between (inclusive) the characters on either side of the dash. Dot (.) Matches any displayable ASCII character. There are two categories of regular expressions; namely simple and complex. Simple regular expressions only specify a single character to be entered from the keyboard, while complex regular expressions specify that more than a single character must be entered from the keyboard. Here are examples of simple regular expressions: Simple Regular Expression What will be accepted ------------------ --------------------- [0-9] Accept any single digit character. [3-7] Accept single digit character between '3' and '7' inclusive. [A-Z] Accept a letter between 'A' and 'Z' inclusive. [A-Za-z] Accept a letter between 'A' Page 89 The C Window Library Page 89 and 'Z' or a letter between 'a' and 'z'. [ABCD] Accept either 'A', 'B', 'C', or 'D'. [A-Za-z0-9] Accept anything between 'A' and 'Z', or 'a' and 'z', or '0' and '9' [0-9ABCD] Accept '0' thru '9', 'A', 'B', 'C', or 'D'. [^A] Accept any character except 'A'. [^A-Z] Accept any character except the characters between 'A' and 'Z' (inclusive). [A-/[] Accept any character between 'A' and '[', inclusive. Please note the use of the forward slash to denote that the left bracket has no special meaning. [A Z] Accept 'A', the space character, or 'Z'. [A/-Z] Accept 'A', the minus (-), or 'Z'. [/-///]] Accept the minus (-), the forward slash (/), or the right bracket (]). [!-&] Accept the ASCII characters between '!' and '&', inclusive. A Accept the letter 'A'. Note that this is equivalent to [A]. [9] Accept the digit '9'. . Accept any character. [] Accept no key and call user defined function (explained later in the UNDEFINED KEYSTROKE PROCESSING section). Page 90 The C Window Library Page 90 Remember, all of the above expressions process only one character entered at the keyboard, even though some of the expressions can accept a variety of characters. As you can see there are many possibilities you can make up. However the above forms of a regular expressions only work for one character entered at the keyboard. What if you want to enter a persons name, address, social security number etc.? You can concatenate (glue together) the regular expressions above to form a chain of regular expressions. This resulting chain is called a complex regular expression. Here are a few examples of complex regular expressions: Regular Expression What will be accepted ------------------ --------------------- [A-Z][0-9] The first character entered must be between 'A' and 'Z'. The second character entered must be between '0' and '9'. [A-Z][^A-Z][0-9] Enter three characters. The first must be between 'A' and 'Z'. The second can be any character except anything between 'A' and 'Z', and the third character must be between '0' and '9'. [1-9][0-9][0-9][0-9][0-9] Enter five characters. The first must be between '1' and '9'. The other four characters must be between '0' and '9'. [A-Z][][0-9] The first character must be between 'A' and 'Z', the second input position calls a user defined function (explained in UNDEFINED KEYSTROKE PROCESSING), and the third character must be between '0' and '9'. As you can see again, the strings can get pretty long if you wanted to setup a thirty character input specification, for instance, a persons name. To save time typing, you can use a multiplying factor in the regular expression. A multiplying factor is a number that is placed before a simple regular expression to denote that the simple regular expression is repeated. Here are a few examples: Page 91 The C Window Library Page 91 Regular Expression What will be accepted ------------------ --------------------- 25[A-Z] Enter twenty-five characters. All the characters must be between 'A' and 'Z'. 10[0-9] Enter ten characters. All must be between '0' and '9'. 5[A-C] 3[1-3] Enter nine characters. The first five must be between 'A' and 'C' the sixth must be the space character, and the last three must be between '1' and '3'. Please note the space embedded in the string just before the multiplying factor 3. [1-9]2X/[5[^A-Z]/1 Enter nine characters. The first must be between '1' and '9'. The second and third must be 'X'. The fourth is the left bracket ([). The next five characters entered can be any character except anything between 'A' and 'Z', and the last character to accept is a '1'. Please note the use of the forward slash just before the second left bracket and just before the last character ('1'). The forward slash before the '1' makes sure the '1' is not to be confused with a multiplying factor of 1. [A-Z]/.. Enter three characters. The first must be between 'A' and 'Z'. The second is the '.', and the third is any character. 10[A-Z]3[] Enter thirteen characters. The first ten must be between 'A' and 'Z', and the last three input positions will call a user defined undefined key function (explained later in the UNDEFINED KEYSTROKE PROCESSING section). The only limitation to what you can do with regular expressions is that you cannot nest regular expressions. For example: [A-[A-Z]] or 20[20[a-z]] It is ok to say [9-0] instead of [0-9]. They are both equivalent and both accepted by The C Window Library, so there is no need to know your ASCII table by heart, although it is advantageous to learn it if you want to create Page 92 The C Window Library Page 92 sophisticated regular expression strings. You can even use the IBM extended character set (ASCII values above 127) in the regular expression string. Editing Input ------------- The C library function gets(x), gets a string from the keyboard and points the character pointer x to the string. This function has limited editing capabilities. The only keys recognized are the backspace, which serves as a destructive backspace (erases character immediately to the left) and the enter key when the user has typed in the desired string. With The C Window Library, you have much more editing capabilities. The editing functions have the following default key values: Mapped Function Key Position -------- --- ------ Move cursor left Left Arrow 0 Move cursor right Right Arrow 1 Delete character at cursor Del (on keypad) 2 Toggle Insert/Overwrite mode Insert (on keypad) 3 Erase Input and go to first column ^E 4 Destructive backspace Backspace 5 Accept Input and return Enter 6 Accept default and return Escape 7 Go to first column Home 8 Move cursor to last char. entered End 9 Here is a list of what the key functions perform: Move cursor left - Moves the cursor left one character. If the beginning of the input field is encountered the cursor is not moved. Move cursor right - Moves the cursor right one character. If the end of the input field is encountered, the cursor is not moved. Delete character at cursor - Deletes the character at the position of the cursor. If in insert mode, any input to the right of the cursor is moved one character to the left. If in overwrite mode, no characters are moved. Toggle Insert/Overwrite Mode - toggles the input between insert and overwrite mode. If Page 93 The C Window Library Page 93 in insert mode, the default cursor is an underline cursor. If in overwrite mode, the default cursor is a full block. Erase Input - Deletes all characters inputted and moves the cursor to the first input position. Destructive Backspace - deletes the character immediately to the left of the cursor and moves the cursor to the left one character. If insert mode is on, the characters from the current cursor position to the end of the input field are also moved. Accept string - Accepts the string that is inputted and returns the string. Accept default and return - Returns the default string given to the input routine. Go to first column - Moves cursor to the first input position. Go to last character - Moves cursor to the last character in the current input string. The keys used to perform these functions can be changed. The mapped position is the offset in a table of key functions. By changing the value there, you can change the key used to perform these functions. If you do want to change these keys, I recommend using the key definitions found in the keycodes.h file. For example, if you wanted Control-B to be the destructive backspace you would do as follows: window_edit_key[5] = CTRLB; The table of key functions is stored in the array window_edit_key. The CTRLB stands for Control-B and its definition is found in the keycodes.h file. To totally undefine a key definition, assign a 0 to the desired array position in window_edit_key. For example: window_edit_key[2] = 0; undefines the delete character at cursor definition. When changing keys, make sure that the definitions all have unique key combinations. If you desire more keystrokes for a particular key function, see Undefined Keystroke Processing below. Page 94 The C Window Library Page 94 Last Key Value -------------- On exit of any of the input functions, the global integer last_key_hit contains the ascii code (scan code) of the key that was used to exit the input function. Default Cursor Types and Editing Mode ------------------------------------- By default, The C Window Library starts editing input in overstrike mode. This means that characters are overwritten when the cursor is placed on a character. The opposite of overstrike mode is insert mode, which pushes the characters to the right of the cursor over by one input position when a character is entered. Also, the default cursor type for overstrike mode is a block cursor, and the default cursor for insert mode is a thin cursor. You can change the startup mode, as well as the cursor types. The global variables default_cursor_type and default_cursor_mode store the values of the cursor shapes and the startup mode. The default_cursor_type is an array of two integers. The OVERSTRIKEMODE constant is the position in the default_cursor_type array of where the overstrike shape of the cursor is stored. The INSERTMODE constant is the position in default_cursor_type of where the insert shape of the cursor is stored. Here is an example of how you would change the cursor types. #include "window.h" main() { WindowInitializeSystem(); /*...*/ /* Some code */ default_cursor_type[OVERSTRIKEMODE] = CREATE_CURSOR_SHAPE(6,7); default_cursor_type[INSERTMODE] = THIN; } The CREATE_CURSOR_SHAPE() macro creates a cursor shape by using the first argument as the starting scan line of the cursor, and the second argument as the ending scan line. Refer to VIDEO MACROS section for more information on CREATE_CURSOR_SHAPE(). The THIN constant is a predefined constant that stands for a thin cursor. The other predefined constants for cursor shapes are BLOCK and INVISIBLE. To change the startup mode when an input function is called, Page 95 The C Window Library Page 95 you must change the default_cursor_mode global variable. Here is how you would change the default mode: #include "window.h" main() { WindowInitializeSystem(); /*...*/ /* Some code */ default_cursor_mode = OVERSTRIKEMODE; } Use the constants OVERSTRIKEMODE and INSERTMODE for the desired mode. Editing using a character mask ------------------------------ The C Window Library also provides input functions that use character masks. For example to enter a date, you might want the user to enter a date in MM-DD-YY format. Instead of the user having to enter the hyphens, it would be advantageous if the input field already had hyphens, and the cursor will advance or back up to the next input position, jumping over any hyphens encountered. You can accomplish this by using a character mask. The mask is a character string which is made up of displayable characters, and a special character used to denote an input position. For example, a date mask would look like this: __-__-__ The hyphens are displayed in the window, but the underscores are not displayed. The underscores are used as a place holder, i.e. a place where input is expected. By default, the input position character is an underscore, but you can change this. Another example would be a social security mask: ___-__-____ a telephone mask: (___) ___-____ ext: ____ another date mask: __/__/__ If a character is deleted or inserted, the input manager is smart enough to move characters so that they do not clobber the characters that are not part of the input field. Page 96 The C Window Library Page 96 Editing Functions ----------------- The following are functions that can be used to edit input with The C Window Library. WindowGetString() ----------------- The WindowGetString() function gets a string from a window starting at a certain row and column of the window. Here is the prototype: int WindowGetString(WPOINTER w, int row, int col, char *buffer, int fillchar, int minchars, int maxwidth, int options, int startpos, char *regexp) The first argument is the window pointer. The second and third arguments are the row and column of where the input begins. The fourth argument is a pointer to a character buffer where the input characters will be stored. Whatever null terminated string is stored in the character buffer prior to calling WindowGetString() will be used as a default string. For example: strcpy(str,"ABC"); WindowGetString(w,2,1,str,' ',3,3,0,"3[A-Z]"); The default value of "ABC" will be displayed in the window when WindowGetString() is called. Therefore, make sure that your string buffer has a 0 in the 0th position if you want to make sure your input is empty when WindowGetString() is called. When inputting information, hitting the Escape key (or whatever the current key definition is for window_edit_key[7]) will abort input and will return the original default string. The fifth argument is the fill character. This character is used to fill any unfilled input positions on the window. Instead of having spaces for unfilled positions, you can have any character. Try ASCII 177 or the underline character. You may like the effect. The sixth argument is the minimum number of characters to accept. If the number of characters entered is less than minchars, the input manager will not accept the input. However, you can change this by allowing the input manager to call a user defined routine when it detects that the minimum number of characters was not satisfied. More information on this later in this section. Page 97 The C Window Library Page 97 The seventh argument is the maximum width of the displayable input field. This argument allows for scrollable input fields. If the maximum width of the displayable field is less than the total number of characters in the input field, the field will scroll right and left depending on the input position. If the input cursor exceeds the right edge of the displayable field, the input is scrolled right until the next input position is visible. If the cursor is moved beyond the left edge of the displayable field, the input is scrolled left until the previous input position comes into view. Scrolling input fields allow for large input fields in small windows. The eighth argument is an integer representing the various options available for the input field. The various options available will be discussed later on. The ninth argument is the starting position in the input string of where the cursor will be placed. Position numbers start from 1 to the maximum number of input positions. For most applications, the starting position is usually 1. If the starting position is not within bounds of the input string, the starting position is assumed to be 1. The last argument is the regular expression to use for the input. Make sure that the input buffer you provide is large enough to hold the maximum number of characters plus one more character for the terminating null character. More Examples: WindowGetString(w,2,1,str,' ',1,1,NO_OPTIONS,1,"[YyNn]"); This will accept one character but only if the character is 'Y','y','N', or 'n'. Another example is this: WindowGetString(w,2,1,str,' ',5,5,NO_OPTIONS,1,"5[0-9]"); This will allow the user to enter five digit characters. To accept all characters, use this: WindowGetString(w,2,1,str,' ',3,3,NO_OPTIONS,1,"."); Example Program: #include "window.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; Page 98 The C Window Library Page 98 char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is NULL */ WindowWriteString(w,"Enter Your first name :",1,1); WindowGetString(w,2,1,buffer,' ',0,40,NO_OPTIONS,1,"40."); WindowWriteString(w,"You entered the following:",3,1); WindowWriteString(w,buffer,4,1); GET_KEY(); WindowWriteString(w,"Now Enter your last name:",6,1); /* Note that the last string is now used as a default */ WindowGetString(w,7,1,buffer,' ',0,40,NO_OPTIONS,1,"40."); WindowWriteString(w,"You entered the following:",8,1); WindowWriteString(w,buffer,9,1); } If there are no errors, WindowGetString() returns NO_ERROR. If there are errors, WindowGetString() returns the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen()) NO_HEAP_MEM if there is not enough memory to allocate for internal buffers. NO_INPUT_CHARS if the regular expression indicates no characters to accept. WindowGetStringAttr() --------------------- The WindowGetStringAttr() function is the same as the WindowGetString() function described above except that a video attribute is used for the input entered. Here is the prototype: int WindowGetStringAttr(WPOINTER w, int row, int col, char *buffer, int fillchar, int minchars, int maxwidth, int options, int startpos, int attr, char *regexp) Page 99 The C Window Library Page 99 Note that attr is the tenth argument. This is the video attribute to use when receiving input. Example Program: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is NULL */ WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter Your first name :",1,1); WindowGetStringAttr(w,2,1,buffer,' ',0,40,NO_OPTIONS,1, REVERSE,"40."); WindowWriteString(w,"You entered the following:",3,1); WindowWriteString(w,buffer,4,1); GET_KEY(); WindowWriteString(w,"Now Enter your last name:",6,1); /* Note that the last string is now used as a default */ WindowGetStringAttr(w,7,1,buffer,' ',0,40,NO_OPTIONS,1, REVERSE,"40."); WindowWriteString(w,"You entered the following:",8,1); WindowWriteString(w,buffer,9,1); } The return values for WindowGetStringAttr() are the same as WindowGetString(). WindowGetMaskString() --------------------- The WindowGetMaskString() function is the same as the WindowGetString() except that a character mask is used when editing the input. Here is the prototype: int WindowGetMaskString(WPOINTER w, int row, int col, char *buffer, char *mask, int fillchar, int minchars, int maxwidth, int options, int startpos, char *regexp) Page 100 The C Window Library Page 100 The mask argument is an extra argument. This is the character mask to use when editing the input. The string returned in the buffer does not contain any characters that are used for the mask. For instance, if the mask is "__/__/__", and the string entered is "121589", WindowGetMaskString() will place "121589" into the buffer. If you want to create a string with the components separated according to a mask pattern, use the TranslateStringToMaskString() function described later in the manual. Default strings must be set up 'unmasked'. For instance, if you wanted the default date to be "12/15/89", and the character mask is "__/__/__", your string buffer should contain "121589" before calling WindowGetMaskString(). This same rule applies to any input functions that use a character mask. Example: #include "window.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define TELMASK "(___)___-____ ext:____" #define SSMASK "___-__-____" WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter Your Telephone No.",1,1); WindowGetMaskString(w,2,1,buffer,TELMASK,' ',0,40, NO_OPTIONS,1,"40."); WindowWriteString(w,"You entered the following phone no:", 3,1); WindowWriteString(w,buffer,4,1); GET_KEY(); memset(buffer,0,sizeof(buffer)); WindowWriteString(w,"Now Enter your Soc. Sec. Number:", 6,1); WindowGetMaskString(w,7,1,buffer,SSMASK,' ',0,40, NO_OPTIONS,1,"40."); WindowWriteString(w,"You entered the following:",8,1); WindowWriteString(w,buffer,9,1); } If there are no errors, WindowGetMaskString() returns NO_ERROR. Page 101 The C Window Library Page 101 If there are errors, WindowGetMaskString() returns the following: BAD_WINDOW if the window does not exist. WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen()) NO_HEAP_MEM if there is not enough memory to allocate for internal buffers. WindowGetMaskStringAttr() ------------------------- The WindowGetMaskStringAttr() functions works the same way as WindowGetMaskString() except that WindowGetMaskStringAttr() allows you to specify a video attribute to use for the characters that are entered. Here is the prototype: int WindowGetMaskStringAttr(WPOINTER w, int row, int col, char *buffer, char *mask, int fillchar, int minchars, int maxwidth, int options, startpos, int attr, char *regexp) Example: #include "window.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) #define TELMASK "(___)___-____ ext:____" #define SSMASK "___-__-____" WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter Your Telephone No.",1,1); WindowGetMaskStringAttr(w,2,1,buffer,TELMASK,' ',0,40, NO_OPTIONS,1,REVERSE,"40."); WindowWriteString(w,"You entered the following phone no:", 3,1); WindowWriteString(w,buffer,4,1); Page 102 The C Window Library Page 102 GET_KEY(); memset(buffer,0,sizeof(buffer)); WindowWriteString(w,"Now Enter your Soc. Sec. Number:",6,1); WindowGetMaskStringAttr(w,7,1,buffer,SSMASK,' ',0,40, NO_OPTIONS,1,REVERSE,"40."); WindowWriteString(w,"You entered the following:",8,1); WindowWriteString(w,buffer,9,1); } The return values for WindowGetMaskStringAttr() are the same as WindowGetMaskString(). Getting Passwords ----------------- The C Window Library also allows you to receive hidden input. The functions to perform this are WindowGetPassword(), WindowGetMaskPassword(), WindowGetPasswordAttr() and WindowGetMaskPasswordAttr(). These functions are similar to the other WindowGetxx() functions. except that a character specified by you is displayed instead of the actual key pressed. WindowGetPassword() ------------------- The WindowGetPassword() function gets hidden input from a window. Here is the prototype: int WindowGetPassword(WPOINTER w, int row, int col, char *buffer, int fillchar, int passchar, int minchars, int maxwidth, int options, int startpos, char *regexp) The first argument is the window pointer. The second and third arguments are the (row,col) to start receiving input. The fourth argument is the buffer to store the inputted characters. The fifth argument is the character to use to fill empty input positions on the screen. The sixth argument is the character to display to the screen when a key is pressed. The last four arguments are the same as the WindowGetString()'s last four arguments. For example, if the user typed "ABCDEF", and the passchar is '*', the screen will display "******". Notice the asterisk is displayed instead of the actual characters inputted. Example Program: #include "window.h" #include <string.h> Page 103 The C Window Library Page 103 #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter A Password",1,1); WindowGetPassword(w,2,1,buffer,' ','*',0,40,NO_OPTIONS, 1,"40."); WindowWriteString(w,"You entered the following:",3,1); WindowWriteString(w,buffer,4,1); } The return values for WindowGetPassword() are the same as WindowGetMaskString(). WindowGetPasswordAttr() ----------------------- The WindowGetPasswordAttr() function is the same as WindowGetPassword() except that a video attribute is specified for the input characters. Here is the prototype: int WindowGetPasswordAttr(WPOINTER w, int row, int col, char *buffer, int fillchar, int passchar, int minchars, int maxwidth, int options, int startpos, int attr, char *regexp) Please note that the attribute argument is the next to last argument in the function. Example Program: #include "window.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; char buffer[80]; Page 104 The C Window Library Page 104 main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter A Password",1,1); WindowGetPasswordAttr(w,2,1,buffer,' ','*',0,40, NO_OPTIONS,1,REVERSE,"40."); WindowWriteString(w,"You entered the following:",3,1); WindowWriteString(w,buffer,4,1); } The return values for WindowGetPasswordAttr() are the same as WindowGetMaskString(). WindowGetMaskPassword() ----------------------- The WindowGetMaskPassword() function works just like WindowGetPassword() except that a character mask is supplied. Here is the prototype: int WindowGetMaskPassword(WPOINTER w, int row, int col, char *buffer, char *mask, int fillchar, int passchar, int minchars, int maxwidth, int options, int startpos, char *regexp) Example: #include "window.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define CREDITCARDMASK "____-____-____-____" WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); Page 105 The C Window Library Page 105 buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter A Credit Card #",1,1); WindowGetMaskPassword(w,2,1,buffer,CREDITCARDMASK,' ','*', 0,40,NO_OPTIONS,1,"40."); WindowWriteString(w,"You entered the following:",3,1); WindowWriteString(w,buffer,4,1); } The return values for WindowGetMaskPassword() are the same as WindowGetMaskString(). WindowGetMaskPasswordAttr() --------------------------- The WindowGetMaskPasswordAttr() function works just like WindowGetMaskPassword() except that a video attribute is supplied. Here is the prototype: int WindowGetMaskPasswordAttr(WPOINTER w, int row, int col, char *buffer, char *mask, int fillchar, int passchar, int minchars, int maxwidth, int options, int startpos, int attr, char *regexp) Example: #include "window.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) #define CREDITCARDMASK "____-____-____-____" WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter A Credit Card #",1,1); WindowGetMaskPasswordAttr(w,2,1,buffer,CREDITCARDMASK,' ', '*',0,40, NO_OPTIONS,1,REVERSE, "40."); Page 106 The C Window Library Page 106 WindowWriteString(w,"You entered the following:",3,1); WindowWriteString(w,buffer,4,1); } The return values for WindowGetMaskPasswordAttr() are the same as WindowGetMaskString(). Undefined Keystroke Processing ------------------------------ Another powerful feature of the input functions is that you can call a function for keys that are not in the current key definitions. For instance, say you want the Enter key AND Control-R to mean accept the input. Since there is only room for one definition for accept input, you can write a function that checks for the Control-R key, and return a number to the input manager as to what action to take. The undef_fkey_func and undef_akey_func function pointers --------------------------------------------------------- There are two global variables, undef_fkey_func and undef_akey_func. Both of these function pointers are defined in the file key.h. These two variables are pointers to functions that return an integer. By setting these functions to point to your own functions, you can process undefined keystrokes yourself and return to the input manager what action to take. The undef_fkey_func is used to define keys that are not normal ASCII keys. For instance, Control key and Alt key combinations, the F-keys, PgDn and PgUp, etc. The undef_akey_func is used to define normal ASCII keys (keys with ASCII values between 32 and 255, inclusive). Whenever an undefined key is encountered, the input manager will pass the string that has been currently entered, the current key pressed, the current position number of the character being processed, and a pointer to a new position to place the input cursor. The prototype for this function is as follows: int (*undef_fkey_func)(char *str,int key, int pos,int *newposptr) The prototype to the undef_akey_func is similar to the one above. The str is a pointer to a null-terminated string of characters that has been currently entered. For instance, if Page 107 The C Window Library Page 107 the string currently entered is ABC123 str will point to "ABC123". The second argument is the last key that was pressed. You should use the values defined in the header file "keycodes.h" if you want to check for non-ascii keys. This will ensure that you are properly checking the keystroke desired. For instance, if you want to check if the key pressed was the Page Up key, use the constant PGUP defined in keycodes.h. The third argument is an integer representing the position number of the current character that the cursor is on. The first character is at position number 0, the second character in the input field is 1, etc. If there is an input mask (as in WindowGetMaskString() and WindowGetMaskStringAttr()) the position number does not include any characters that are used to create the non-input positions. For instance: "__/__/__ " 01 23 45 The numbers under the mask are the position numbers for each character. The fourth argument is a pointer to an integer representing a new position to move the cursor. Use of this pointer will be explained later. for this argument will be made evident later. The reason for the third argument being a pointer rather than an integer will be evident later on. Specifying when to call an undefined key function in a Regular Expression ------------------------------- An empty bracketed simple regular expression tells the input manager to call the undefined keystroke function. An example of this type of regular expression is as follows: Regular Definition Expression ---------- ---------- [A-Z][] The first input position must be btween 'A' and 'Z', and the second position will automatically call the user defined undefined keystroke function. 20[] All twenty input positions Page 108 The C Window Library Page 108 will call the undefined keystroke function. 3[0-9]2[]2[A-Z] The first three input positions must be between '0' and '9', the next two input positions automatically call the undefined keystroke function, and the last two positions must be between 'A' and 'Z'. If you use this form of a regular expression, you MUST have defined an undefined keystroke function. If you did not define one, you will more than likely get into an infinite loop. Using this form of regular expression combined with the return values (defined below) that can be returned to the input manager, you will virtually have total control of the way the input is handled. Return Values To The Input Manager ---------------------------------- When writing your function you must return an integer to the input manager. This integer will inform the input manager as to what action to take. Here are a list of the return values and what they inform the input manager: Return Action to Value Take ------ --------- DONT_PROCESS Do not Process keystroke and continue getting input. MOVE_CURSOR_LEFT Move cursor left. MOVE_CURSOR_RIGHT Move cursor right. DELETE_AT_CURSOR Delete character at cursor. TOGGLE_INSERT Toggle Insert/Overwrite mode. DESTRUCT_BACKSPACE Destructive Backspace. ACCEPT_INPUT Accept Input and return string. ACCEPT_DEFAULT Accept default string and return. ERASE_INPUT Erase Input and go to first Page 109 The C Window Library Page 109 character in input field. GOTO_FIRST Go to first input character in field. GOTO_LAST Move cursor to last input character in field. MOVE_TO_CHARACTER Move cursor to input position specified in the *pos argument. INSERT_CHARACTER Accept character as valid and insert it at the current cursor position. The MOVE_TO_CHARACTER return value moves the input cursor to the position in the input string specified in the fourth argument of undef_akey_func or undef_fkey_func. If you recall, the fourth argument was a pointer to an integer. The INSERT_CHARACTER return value only applies to the function pointed to by undef_akey_func. These user-defined functions can do anything, not just process keystrokes. For instance, if you want F1 to be a help key, where the help function is in a function called do_help() you must make sure that: a) the F1 key is undefined (not defined in the window_edit_key array) b) the undef_fkey_func function pointer points to your function c) return an integer to the input manager from your function. Here is a typical way that this would be set up: #include "window.h" /* ... Other #includes and #defines */ int do_help(); /* define help function */ main() { WindowInitializeSystem(); /* ...Some code */ undef_fkey_func = do_help; WindowGetString(/* ... Parameters */); /* ... Other code */ } Page 110 The C Window Library Page 110 int do_help(char *str, int ch, int pos, int *newpos) { if (ch == F1) /* check for F1 */ { /* help function goes here */ return DONT_PROCESS; /* make sure input manager does not process this or any other undefined keystroke */ } else { *newpos = 3; /* move input cursor to the third input position */ return MOVE_TO_CHARACTER /* let input manager know we want to move the input cursor */ } } With this flexibility in the input functions, you can totally control how input is handled. Page 111 The C Window Library Page 111 Input Options ------------- In the previous examples, the available options were discussed briefly. These options provide further control of the input functions. Here is a list of the options that are available: Option Definition ------ ---------- UPPERCASE Translates and displays lower case to upper case. LOWERCASE Translates and displays upper case to lower case. CHECKSPACES Spaces are counted when determining whether the minimum number of characters are entered. ENHANCEDKEY Use the enhanced keyboard keys and distinguish between keypad keys and separate cursor pad keys. Also detect F11 and F12 keys. CHECKREGEXP Check to see if all characters entered agree with the regular expression provided. AUTORETURN Automatically accept the input when a character in the last input position is entered. HOMECURSOR Move scrolled input back to the first character in the input string when input is accepted. CLEARFIELD Clears the input field if the first key pressed is recognized by the regular expression as a valid input key. If a cursor movement key is pressed first, the field is not cleared if any subsequent input keys are pressed. USEMOUSE Utilize the mouse to move the cursor in the input field. NO_OPTIONS No options desired. Page 112 The C Window Library Page 112 UPPERCASE --------- The UPPERCASE option converts and displays all lower case letters to upper case while the user is inputting characters. LOWERCASE --------- The LOWERCASE option converts and displays all upper case letters to lower case while the user is inputting characters. CHECKSPACES ----------- The CHECKSPACES option will cause the input manager to count any embedded spaces when determining whether the minimum number of characters are reached. Trailing spaces are counted only if the user explicitly put them there. ENHANCEDKEY ----------- The ENHANCEDKEY option will distinguish between the cursor keys on the keypad from the dedicated cursor keys on the enhanced keyboards as well as the Ins, Home, Del, PgUp and PgDn keys. Also the F11 and F12 keys will be detected. CHECKREGEXP and the reg_exp_error_func function pointer ------------------------------------------------------- The CHECKREGEXP option will check to make sure that every character inputted is a valid character according to the regular expression. When inserting or deleting characters during input, characters may be moved left or right depending on whether the input is in insert or overwrite mode. When the characters are moved, the resulting pattern of characters may not match the regular expression desired. For instance, if the regular expression is "3[A-Z]2[0-9]", meaning 3 characters between A and Z followed by 2 characters between 0 and 9, and the current input entered is as follows : ABC34 If the cursor is currently under the 'C', the delete key is pressed, and the input is currently in insert mode, the '34' will be moved one character to the left. The resulting input would then look like this: AB34 As you can see, the input does not match the regular Page 113 The C Window Library Page 113 expression "3[A-Z]2[0-9]" because the '3' is in a position that should be occupied by a letter. When the CHECKREGEXP option is chosen, each position is checked when the user wants to accept the string, not while the user is entering characters. If the input is not OK, the input manager will not accept the string. You can override this by setting the reg_exp_error_func function pointer. The global function pointer reg_exp_error_func is prototyped as follows: int (*reg_exp_error_func)(char *buf, int nomatch); where buf is the current string entered, and nomatch is the position of the first non-matching character that did not match the regular expression. The first character of the string is at position 0. Your function must return an integer back as to what to do. There are two valid return values, namely ACCEPT_INPUT and DONT_PROCESS. A return value of ACCEPT_INPUT will accept the input, even though all of the characters do not match the regular expression. DONT_PROCESS tells the input manager to keep getting input. Here is an example: int my_check_func(); main() { ... reg_exp_error_func = my_check_func; WindowGetString(other parameters, CHECKREGEXP, "[A-Z][0-9]"); ... } int my_check_func(char *buf, int mistake_pos) { /* Assume w is initialized and open for writing */ WindowPrintf(w, "Illegal input for %s. Illegal character at position %d",buf, mistake_pos); GET_KEY(); WindowHide(w,NOEFFECT); return DONT_PROCESS; } The above example shows a function called my_check_func() which will be called when the input manager detects that all of the characters in the buffer buf do not match the regular Page 114 The C Window Library Page 114 expression. The function displays a message in a window and waits for a key to be pressed. Then the function returns DONT_PROCESS back to the input manager. AUTORETURN ---------- The AUTORETURN will automatically accept the input and return to the calling function if the cursor is on the last input position and the user types a valid character. Of course, if CHECKREGEXP is on, the input is checked for validity. HOMECURSOR ---------- The HOMECURSOR options will scroll an input field back to the first position when the input is accepted. CLEARFIELD ---------- The CLEARFIELD option will automatically clear the input field of any characters if the first key struck is a key recognized as a valid input key, and the character is displayed in the input position. If the first key struck is a cursor movement key or a delete character key (destructive backspace or delete character), any valid input key that is subsequently struck does not clear the field, but is recorded in the input field. USEMOUSE -------- This option can only be used if you have access to The C Window Library MouseLib functions, the system has a mouse installed, and the mouse has been activated. By positioning the mouse cursor to any valid input position in the input field and pressing the mouse button defined in the global integer variable field_button_press, the cursor is automatically moved to that input position. If the CLEARFIELD option is used in conjunction to USEMOUSE, any subsequent input will not clear the field if the mouse was used to move the cursor. NO_OPTIONS ---------- No field options desired. In other words, all of the options defined above are turned off. Page 115 The C Window Library Page 115 Examples of Input Options ------------------------- Examples: a) WindowGetString(w,1,1,str,' ',1,1,UPPERCASE,"[YyNn]"); b) WindowGetString(w,1,1,str,' ',1,1,LOWERCASE,"[YyNn]"); c) WindowGetStringAttr(w,2,1,str,' ', CREATE_VIDEO_ATTRIBUTE(black,white),1, 1,UPPERCASE | AUTORETURN,"[YyNn]"); d) WindowGetString(w,1,1,str,' ',10,10, UPPERCASE | ENHANCEDKEY,"10."); e) WindowGetString(w,1,1,str,' ',20,10,CHECKREGEXP | HOMECURSOR,"10[A-Z]10[0-9]"); Example a) gets one character and will automatically set this character to upper case. b) same as a) except character is converted to lower case. c) converts one character to uppercase and automatically accepts the input because the input cursor was on the last input position. Note the use of the bitwise OR (|) to set multiple options. d) Converts the input to uppercase and treats extra keys on an enhanced keyboard as different than their "normal" keys. e) On accepting of the input field, the input is checked to see if every position on the input field is checked to see if it matches the regular expression. Once the input is accepted, the input is scrolled back to the first input position. THE num_chars_entered_func FUNCTION POINTER ------------------------------------------- If the number of characters entered is not enough to satisfy the minimum number of characters allowed, by default the input manager will not return until the required number of characters is entered. However, a global function pointer can be assigned to a user-written function that will be called when the input manager detects that the minimum number of characters was not reached. The function pointer num_chars_entered_func is prototyped as follows: Page 116 The C Window Library Page 116 int (*num_chars_entered_func)(char *buf, int minchars); where buf is the current string that is entered, and minchars is the minimum number of characters to expect. Your function must return an integer back as to what to do. There are two valid return values, namely ACCEPT_INPUT and DONT_PROCESS. A return value of ACCEPT_INPUT will accept the input, even though the minimum number of characters was not reached. DONT_PROCESS tells the input manager to keep getting input. Here is an example: int my_min_func(); main() { ... num_chars_entered_func = my_min_func; ... } int my_min_func(char *buf, int m) { /* Assume w is initialized and open for writing */ WindowWriteString(w,"Not enough characters!",1,1); GET_KEY(); WindowHide(w,NOEFFECT); return DONT_PROCESS; } The above example shows a function called my_min_func() which will be called when the input manager detects that the number of characters in the buffer buf, does not meet the minimum requirements. The function displays a message in a window and waits for a key to be pressed. Then the function returns DONT_PROCESS back to the input manager. Other Input Related Functions ----------------------------- There are other input related functions that you can use to translate strings into their character mask equivalents and vice-versa. TranslateStringToMaskString() ----------------------------- This TranslateStringToMaskString() function takes a string Page 117 The C Window Library Page 117 and either places spaces, or the actual mask character between the characters in the string. A pointer to the translated string is returned. Here is the prototype: char *TranslateStringToMaskString(char *buffer, char *mask, char *buf2, int maskchar, int flag) The first argument is a pointer to the string to translate. The second argument is the mask string to use. The third argument is a pointer to the buffer that will store the translated string. The fourth argument is the mask character that is to be used. This character determines where the input positions are. The flag argument tells whether to include spaces between each component, or to use the character in the mask. You must make sure that buf2 is big enough to hold the translated string. The string length of the mask determines how far to translate the string. If the mask string is shorter than the string to translate, the string is truncated up to the last character in the mask. If the string to translate runs out of characters before the mask has been totally scanned, the extra characters in buf2 will either be spaces, or the characters in the mask (not the mask character specified in argument 4) will be copied over. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define DATEMASK "__/__/__" char buf1[] = "123456"; char buf2[9]; WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM, SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); TranslateStringToMaskString(buf1,DATEMASK,buf2,'_',0); WindowPrintf(w, "The original string is %s\nThe translated string is %s\n", buf1,buf2); TranslateStringToMaskString(buf1,DATEMASK,buf2,'_',1); WindowPrintf(w, "The original string is %s\nThe translated string is %s\n", buf1,buf2); } Page 118 The C Window Library Page 118 The example above takes the string "123456" with the mask of "__/__/__". The results of a translate with a flag of 0, and with a flag value of 1, is displayed in window w. The return value for TranslateStringToMaskString() is the pointer to the buffer that holds the translated string. This string is automatically null terminated. TranslateMaskStringToString() ----------------------------- This TranslateMaskStringToString() function does the opposite of TranslateStringToMaskString(). This function takes a string that has been translated with the TranslateStringToMaskString() or contains mask characters and returns the string without the extra characters. Here is the prototype: char *TranslateMaskStringToString(char *buffer, char *mask, char *buf2, int maskchar) The first argument is a pointer to the translated string. The second argument is the mask string to use. The third argument is a pointer to the buffer that will store the resulting string. The fourth argument is the mask character that is to be used. This character determines where the input positions are. You must make sure that buf2 is big enough to hold the new string. The translation stops when either the end of the buffer is reached, or the end of the mask string is reached. Example: #include "window.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define DATEMASK "__/__/__" char buf1[] = "12/34/56"; char buf2[9]; WPOINTER w; main() { memset(buf2,0,sizeof(buf2)); WindowInitializeSystem(); Page 119 The C Window Library Page 119 WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,40,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); TranslateMaskStringToString(buf1,DATEMASK,buf2,'_'); WindowPrintf(w,"The original string is %s\n" "The untranslated string is %s\n", buf1,buf2); } The example above takes the string "12/34/56" with the mask of "__/__/__". The results of the translation is displayed in window w. The return value for TranslateMaskStringToString() is the pointer to the buffer that holds the translated string. This string is automatically null terminated. Page 120 The C Window Library Page 120 VIRTUAL WINDOWS --------------- A virtual window can be thought of as a rectangular area filled with text. This rectangular region can be broken up into rows and columns, just as a normal window can be divided into rows and columns. The differences between a virtual window and a regular window is that a virtual window's dimensions can be larger than the physical screen, and a virtual window is not displayed on the screen. Then what good is it if you cannot display it? You use regular windows to display portions of the virtual window. If a regular window is used to view a virtual window, the regular window is called a viewport. With this method, you can use a viewport to display a virtual window, and then 'pan' around, viewing different sections of the virtual window. Text editors use this method to display files. Scrolling popup menus also use virtual windows. With The C Window Library, you can create virtual windows of any size, up to available user memory. You can have a maximum of 256 virtual windows defined at the same time. Using Windows as Viewports -------------------------- If text is written to a virtual window, and there is a viewport that is displaying the portion of the virtual window that has changed, the viewport will show the change immediately. You do not have to "repaint" or "refresh" the viewport to show an updated change. That is handled internally in The C Window Library. However, there is an option that will "freeze" a viewport, i.e. will not update automatically, if there is a change in the virtual window. When the viewport is unfrozen, the changes to the virtual window are than displayed. Attributed and Non-Attributed Virtual Windows --------------------------------------------- There are two types of virtual windows. You can have either a virtual window with its own video attributes or a virtual window which gets its video attributes from the viewport that is displaying the virtual window. Virtual windows without attributes use half as much memory as a virtual window with attributes, but attributed virtual window's are more flexible. For instance, lets say you have highlighted some text in the virtual window. If the virtual window is not attributed, you must write the highlight attribute to the viewport window using one of the window functions Page 121 The C Window Library Page 121 (WindowWriteStringAttr() for example), since the virtual window does not have the capacity to store the video attribute. If you were to scroll the highlighted portion out of the viewport, you lose the highlight attribute, and must call the window function again to highlight the text, if the text is displayed again in the viewport. With an attributed virtual window, you write the attributes to the virtual window. Since the attributes are stored in the virtual window structure itself, the attributes are retained until you change them. From this point on, virtual windows without attributes are called NOATTRIBUTE virtual windows. Virtual windows with attributes will be called ATTRIBUTE virtual windows. Virtual Window's Logical Cursor ------------------------------- Each virtual window has its own logical cursor. This cursor is updated automatically when calling VirtualPrintf(), and VirtualWriteCharacter() functions, or can be updated manually by calling the VirtualMoveCursor() function. This cursor is independent of the screen cursor. Page 122 The C Window Library Page 122 CREATING VIRTUAL WINDOWS ------------------------ The section will discuss creating virtual windows using the VirtualInitialize() function. VirtualInitialize() ------------------- Virtual windows are created by calling the VirtualInitialize() function. Here is the prototype: VWPOINTER VirtualInitialize(int vwtype, unsigned nrows, unsigned ncols, int attr) The VirtualInitialize() function returns a pointer to a virtual window structure (a VWPOINTER). The first argument to VirtualInitialize() tells whether the virtual window will or will not have its own video attributes. If this argument is NOATTRIBUTE, the virtual window will not have attributes, otherwise if it is ATTRIBUTE, the virtual window will have its own attributes. The second argument is the number of rows of the virtual window. The third argument is the number of columns. The fourth argument is the attribute to use for the virtual window. This argument is ignored if the virtual window is NOATTRIBUTE. Example: #include "window.h" #include <stdio.h> #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw1, /* virtual window pointers */ vw2; main() { WindowInitializeSystem(); /* set up a NOATTRIBUTE virtual window */ vw1 = VirtualInitialize(NOATTRIBUTE,/* virt. window type */ 30, /* Number of rows */ 80, /* Number of cols */ 0); /* Attribute */ /* set up an ATTRIBUTE virtual window */ vw2 = VirtualInitialize(ATTRIBUTE, /* virtual window type */ 30, /* Number of rows */ 100, /* Number of cols */ NORM); /* Attribute */ if (vw1 == (VWPOINTER)0 || vw2 == (VWPOINTER)0 ) /* Check if allocation worked */ printf( "Error in allocating virtual window." Page 123 The C Window Library Page 123 "The error number is %d"", window_error_code); } In the above program, the VirtualInitialize() function is called. This function allocates memory for the virtual window, and does other initializations. Once this function is called, you can write to and read characters from the virtual window. Notice that the first argument to VirtualInitialize() is either the constant NOATTRIBUTE or ATTRIBUTE. Also note that there is a check to see whether the virtual windows could be allocated. If there are no errors, VirtualInitialize() returns a valid VWPOINTER. If there are errors, VirtualInitialize() returns a null VWPOINTER and sets the global variable window_error_code to one of the following: NO_HEAP_MEM if there is not enough memory to allocate for the virtual window. MAX_V_WINDOW if there are already 256 virtual windows defined. Page 124 The C Window Library Page 124 ASSIGNING VIEWPORTS AND CLOSING VIEWPORTS ----------------------------------------- For a virtual window to have any useful purpose, it should be displayed on the screen. However the virtual window may be larger than the physical screen. The problem is solved by using normal windows to display parts of the virtual window. WindowAssignToVirtual() ----------------------- To turn a window into a viewport onto a virtual window, you use the WindowAssignToVirtual() function. Here is the prototype: int WindowAssignToVirtual(WPOINTER w, VWPOINTER vw, unsigned row, unsigned col) The first argument is the window that will be turned into a viewport. The second argument is the virtual window that w will be assigned to. The third and fourth arguments are the (row,col) of the virtual window. This position is where the upper left hand corner of the viewport's text area will be placed. To illustrate this, here is a sample call to WindowAssignToVirtual(): WindowAssignToVirtual(w,vw,5,10) The following description shows how this is to be interpreted: VIRTUAL WINDOW ------------------------------------------------------------ |(1,1) 100,1)| | | | (5,10) of virtual window is equivalent to (1,1) of | | | the viewport. | | v | | ----------------------- | | |(1,1) of the viewport| | | | | | | | VIEWPORT WINDOW | | | |(14,1) (14,30)| | | ----------------------- | | | |(100,1) (100,100) | ------------------------------------------------------------ The viewport relative position of (1,1) is located at (5,10) Page 125 The C Window Library Page 125 of the virtual window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); w = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM, SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteString(vw,"This is a string",1,1); WindowAssignToVirtual(w,vw,1,1); /* Assign viewport to virtual window */ } The above program opens a virtual window, vw, and opens a normal window, w. In the above example, the VirtualWriteString() function is used to write strings to the virtual window. See the WRITING TEXT TO VIRTUAL WINDOWS section for more information on VirtualWriteString(). Once a window is turned into a viewport, nothing is stopping you from using the other window functions. You can still use WindowWriteString(), WindowMove(), WindowPrintf(), etc. Writing text to a viewport window via the normal window functions does not effect the virtual window in any way. If there are no errors, WindowAssignToVirtual() returns NO_ERROR. If there are errors, WindowAssignToVirtual() returns the following values: BAD_WINDOW if the window does not exist. BAD_V_WINDOW if the virtual window does not exist. WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen()). Out of bounds Coordinates ------------------------- The next question is "What do you do if the coordinates given in WindowAssignToVirtual() are out of bounds of the range of the virtual window?". For instance, if the virtual window Page 126 The C Window Library Page 126 has 100 rows, but the call to WindowAssignToVirtual() specifies row 97, and the viewport itself has a height of 10 rows. The window manager will fill the viewport with as much of the virtual window as possible, and will clear the contents of the viewport that are not inside the virtual window. Here is another view of what happens in this case: VIRTUAL WINDOW ---------------------------------------------------------- |(1,1) (100,1)| | | | (97,10) of virtual window is same as (1,1) of | | | the viewport window. | | v | | ----------------------- | | |(1,1) of the viewport| | | | | | |(100,1) | VIEWPORT WINDOW | (100,100) | ----------------------------------------------------------- |This portion of the | | window is cleared | ----------------------- The above picture shows a viewport that is partially contained in the virtual window. The contents of the window above the last row of the virtual window is updated, while the portion of the viewport below the line is cleared. WindowCloseViewport() --------------------- To turn a viewport back to a normal window, WindowCloseViewport() is called. Here is the prototype: int WindowCloseViewport(WPOINTER w, int hide, int effect) where w is the viewport to be turned back into a regular window. When this function is called, the window w is cleared with its own video attribute. The second argument tells if the window is to be hidden. If hide is 1, the window is hidden. If it is 0, the window remains on the screen. The effect argument is a special effect to use when hiding the window. A list of special effects are defined in the DISPLAYING WINDOWS section. This function DOES NOT close the virtual window or does a WindowClose() to the viewport window. Page 127 The C Window Library Page 127 Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); w = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteString(vw,"This is a string",1,1); WindowAssignToVirtual(w,vw,1,1); GET_KEY(); WindowCloseViewport(w,1,NOEFFECT); GETKEY(); } The example above opens a virtual windows and a normal. It then assigns the windows to the virtual window by calling WindowAssignToVirtual(). The program then unassigns the viewport by calling WindowCloseViewport(). If there are no errors, WindowCloseViewport() returns NO_ERROR. If there are errors, WindowCloseViewport() returns the following values: BAD_WINDOW if the window does not exist. BAD_V_WINDOW if the virtual window that w is a viewport on does not exist. WINDOW_NOT_OPEN if the window is not open for writing (use WindowOpen()). Page 128 The C Window Library Page 128 WRITING TEXT TO VIRTUAL WINDOWS ------------------------------- There are several functions that write strings to virtual windows. They are divided into two groups: functions that take null terminated strings as arguments, and functions that use character buffers and a length argument. When any of the text functions are called, any viewport that is displaying any portion of the virtual window that has been changed will display the update. Null Terminated String Functions -------------------------------- VirtualWriteString() -------------------- The VirtualWriteString() function writes a null terminated to a virtual window at a specific row and column of the virtual window. Here is the prototype: int VirtualWriteString(VWPOINTER vw, char *string, unsigned row, unsigned col) The first argument is the virtual window pointer. The second argument is the string to write. The third and fourth arguments are the row and column of the virtual window that the string is to be written to. If the string will exceed the boundaries of the virtual window, the string is truncated. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; /* virtual window pointers */ WPOINTER w1, w2; main() { WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); w1 = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM, SINGLEBOX); w2 = WindowInitialize(BORDER,13,1,20,10,NORM,NORM, DOUBLEBOX); WindowOpen(w1); WindowOpen(w2); WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); VirtualWriteString(vw,"This is a string",1,1); WindowAssignToVirtual(w1,vw,1,1); Page 129 The C Window Library Page 129 WindowAssignToVirtual(w2,vw,1,10); } The example above writes the string "This is a string" to the virtual window at row 1, column 1. The windows w1 and w2 are viewports on the virtual window vw. The window w1 is located at (1,1) of the virtual window, while w2 is located at (1,10) of the virtual window. The window w1 will display "This is a string", but w2 will only display "string" since it is situated at column 10 of the virtual window. If there are no errors, VirtualWriteString() returns NO_ERROR. If there are errors, VirtualWriteString() returns the following values: BAD_V_WINDOW if the virtual window does not exist. V_WINDOW_BOUND if the either row or col is out of bounds of the virtual window. VirtualWriteStringAttr() ------------------------ The VirtualWriteStringAttr() works the same way as the VirtualWriteString() except that a video attribute is used. Here is the prototype: int VirtualWriteStringAttr(VWPOINTER vw, char *string, unsigned row, unsigned col, int attr) The last argument is the video attribute to use. If the virtual window is NOATTRIBUTE, the attribute is ignored, and only the string is written. Any viewports that are assigned to NOATTRIBUTE virtual windows will not reflect the change in the attribute. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); Page 130 The C Window Library Page 130 WindowSaveInitial(0); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); w = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM, SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteStringAttr(vw,"This is a string",1,1,REVERSE); WindowAssignToVirtual(w,vw,1,1); } The example above writes the string "This is a string" in the virtual window with a video attribute defined by the constant REVERSE. If there are no errors, VirtualWriteStringAttr() returns NO_ERROR. If there are errors, VirtualWriteStringAttr() returns the following values: BAD_V_WINDOW if the virtual window does not exist. V_WINDOW_BOUND if the either row or col is out of bounds of the virtual window. NO_ATTRIB if the virtual window is NOATTRIBUTE. If this error occurs, only the string is written. VirtualWriteCenterString() -------------------------- The VirtualWriteCenterString() writes a centered string in a virtual window. Here is the prototype: int VirtualWriteCenterString(VWPOINTER vw, char *string, unsigned row) The row argument is the row to center the string on. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); Page 131 The C Window Library Page 131 vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteCenterString(vw,"This is a string",1); WindowAssignToVirtual(w,vw,1,1); } The above example illustrates the use of VirtualWriteCenterString(). The viewport window w is just used as a guide to display what has happened. If there are no errors, VirtualWriteCenterString() returns NO_ERROR. If there are errors, VirtualWriteCenterString() returns the following values: BAD_V_WINDOW if the virtual window does not exist. V_WINDOW_BOUND if the row is out of bounds of the virtual window. VirtualWriteCenterStringAttr() ------------------------------ The VirtualWriteCenterStringAttr() function works the same way as VirtualWriteCenterString() except that a video attribute is specified. Here is the prototype: int VirtualWriteCenterStringAttr(VWPOINTER vw, char *string, unsigned row, int attr) The attr argument is the video attribute to use. If the virtual window is NOATTRIBUTE, the attribute is ignored and only the string is written to the virtual window. #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); Page 132 The C Window Library Page 132 w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteCenterStringAttr(vw,"This is a string",1, REVERSE); WindowAssignToVirtual(w,vw,1,1); } If there are no errors, VirtualWriteCenterStringAttr() returns NO_ERROR. If there are errors, VirtualWriteCenterStringAttr() returns the following values: BAD_V_WINDOW if the virtual window does not exist. V_WINDOW_BOUND if the row is out of bounds of the virtual window. NO_ATTRIB if the virtual window is NOATTRIBUTE. If this error occurs, only the string is written. VirtualWriteStringCC() ---------------------- The VirtualWriteStringCC() function centers and writes a string around a column of the virtual window (the CC stands for Centered Column). If the string is longer than the width of the virtual window, the string is placed on column 1 is clipped at the right edge of the virtual window. Here is the prototype: int VirtualWriteStringCC(VWPOINTER vw, char *string, unsigned row, unsigned col) The first argument is the window. The second argument is the string. The third argument is the row to write the string, and the last argument is the column to center the string on. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX); WindowOpen(w); Page 133 The C Window Library Page 133 WindowDisplay(w,1,NOEFFECT); VirtualWriteStringCC(vw,"This",1,10); VirtualWriteStringCC(vw,"is",2,10); VirtualWriteStringCC(vw,"centered",3,10); VirtualWriteStringCC(vw,"around",4,10); VirtualWriteStringCC(vw,"column",5,10); VirtualWriteStringCC(vw,"10",6,10); WindowAssignToVirtual(w,vw,1,1); } The example above writes the text centered around column 10 of the virtual window w. The return values for VirtualWriteStringCC() are the same as VirtualWriteString(). VirtualWriteStringCCAttr() -------------------------- The VirtualWriteStringCCAttr() works the same way as the VirtualWriteStringCC() function except that a video attribute is specified. Here is the prototype: int VirtualWriteStringCCAttr(VWPOINTER vw, char *string, unsigned row, unsigned col, int attr) The attribute to use is the last argument. If the virtual window is NOATTRIBUTE, the attr argument is ignored, and only the string is written to the virtual window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteStringCCAttr(vw,"This",1,10,REVERSE); VirtualWriteStringCCAttr(vw,"is",2,10,REVERSE); Page 134 The C Window Library Page 134 VirtualWriteStringCCAttr(vw,"centered",3,10,REVERSE); VirtualWriteStringCCAttr(vw,"around",4,10,REVERSE); VirtualWriteStringCCAttr(vw,"column",5,10,REVERSE); VirtualWriteStringCCAttr(vw,"10",6,10,REVERSE); WindowAssignToVirtual(w,vw,1,1); } The return values for VirtualWriteStringCCAttr() are the same as VirtualWriteStringAttr(). VirtualWriteStringRJ() ---------------------- The VirtualWriteStringRJ() function writes a right justified string in a virtual window. Here is the prototype: int VirtualWriteStringRJ(WPOINTER w, char *string, unsigned row, unsigned col) The first argument is the virtual window. The second argument is the string. The third argument is the row to write the string, and the last argument is the column to place the right edge of the string. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM, SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteStringRJ(vw,"This",1,10); VirtualWriteStringRJ(vw,"is",2,10); VirtualWriteStringRJ(vw,"right",3,10); VirtualWriteStringRJ(vw,"justified",4,10); VirtualWriteStringRJ(vw,"on ",5,10); VirtualWriteStringRJ(vw,"column",6,10); VirtualWriteStringRJ(vw,"10",7,10); WindowAssignToVirtual(w,vw,1,1); } The example above writes the text right justified on column Page 135 The C Window Library Page 135 10 of the virtual window. The return values for VirtualWriteStringRJ() are the same as VirtualWriteString(). VirtualWriteStringRJAttr() -------------------------- The VirtualWriteStringRJAttr() writes a right justified string in a virtual window, and allows you to specify a video attribute. Here is the prototype: int VirtualWriteStringRJAttr(WPOINTER w, char *string, unsigned row, unsigned col, int attr) The last argument is the attribute to use. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); w = WindowInitialize(BORDER,1, 1,50,12,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteStringRJAttr(vw,"This",1,10,REVERSE); VirtualWriteStringRJAttr(vw,"is",2,10,REVERSE); VirtualWriteStringRJAttr(vw,"right",3,10,REVERSE); VirtualWriteStringRJAttr(vw,"justified",4,10,REVERSE); VirtualWriteStringRJAttr(vw,"on ",5,10,REVERSE); VirtualWriteStringRJAttr(vw,"column",6,10,REVERSE); VirtualWriteStringRJAttr(vw,"10",7,10,REVERSE); WindowAssignToVirtual(w,vw,1,1); } The example above writes the text right justified on column 10 of the virtual window. If the virtual window is NOATTRIBUTE, only the string is written. The return values for VirtualWriteStringRJAttr() are the same as VirtualWriteStringAttr(). Page 136 The C Window Library Page 136 Length Controlled Functions --------------------------- VirtualWriteCharacters() ------------------------ The VirtualWriteCharacters() writes a specified number of characters from a buffer to the virtual window. Here is the prototype: int VirtualWriteCharacters(VWPOINTER vw, char *buffer, unsigned row, unsigned col, unsigned length) The first argument is the virtual window. The second argument is the buffer where the characters are stored. The third and fourth arguments are the (row,col) of where the characters will be placed in the virtual window. The last argument is the number of characters from buffer that will be written. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; VWPOINTER vw; char buf[] = "Hello World!!"; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteCharacters(vw,buf,1,1,11); VirtualWriteCharacters(vw,buf,2,1,13); WindowAssignToVirtual(w,vw,1,1); } The return values for VirtualWriteCharacters() are the same as VirtualWriteString(). Page 137 The C Window Library Page 137 VirtualWriteAttributes() ------------------------ The VirtualWriteAttributes() writes a specified number of attributes from a buffer to the virtual window. Here is the prototype: int VirtualWriteAttributes(VWPOINTER vw, char *buffer, unsigned row, unsigned col, unsigned length) The first argument is the virtual window. The second argument is the buffer where the attributes are stored. The third and fourth arguments are the (row,col) of where the attributes will be placed in the virtual window. The last argument is the number of attributes from buffer that will be written. If the window is NOATTRIBUTE, this function does nothing. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; VWPOINTER vw; char buf[13]; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); for (i=0;i<13;i++) if (i % 2) buf[i] = NORM; else buf[i] = REVERSE; w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteString(vw,"Hello World!!",1,1); VirtualWriteAttributes(vw,buf,1,1,13); WindowAssignToVirtual(w,vw,1,1); } The return values for VirtualWriteAttributes() are the same as VirtualWriteStringAttr(). Page 138 The C Window Library Page 138 VirtualWriteCharAndAttr() ------------------------- The VirtualWriteCharAndAttr() function writes a string of character/attribute pairs to a virtual window. Use this function if you have created a string of character/attribute pairs, and want to output them easily. The string consists of character and attributes in the following manner: char-attr-char-attr... Each character is followed by its corresponding video attribute. Here is the prototype: int VirtualWriteCharAndAttr(VWPOINTER vw, char *buffer, unsigned row, unsigned col, unsigned length) The first argument is the virtual window. The second is the buffer where the character and attributes are stored. The third and fourth is the (row,col) position in the virtual window to write, and the length argument is the number of character/attribute pairs from the buffer to write. Please note the difference in the meaning of the length argument in this function as opposed to its use in the preceding functions. If the virtual window is NOATTRIBUTE, nothing is written to the virtual window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; VWPOINTER vw; char buf[26]; char *str = "Hello World!!"; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); for (i=0;i<26;i+=2,str++) { buf[i] = *str; buf[i+1] = NORM; } VirtualWriteCharAndAttr(vw,buf,1,1,13); Page 139 The C Window Library Page 139 WindowAssignToVirtual(w,vw,1,1); } The return values for VirtualWriteCharAndAttr() are the same as VirtualWriteStringAttr(). VirtualWriteRepeatAttribute() ----------------------------- The VirtualWriteRepeatAttribute() function writes an attribute a specified number of times to a virtual window. Here is a prototype: int VirtualWriteRepeatAttribute(VWPOINTER vw, int attr, unsigned row, unsigned col, int count) The attr argument is the attribute to use. The count argument specifies the number of times to write the attribute attr to the virtual window starting at (row,col). If the virtual window is NOATTRIBUTE, this function returns an error. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; VWPOINTER vw; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteString(vw,"Hello World!!",1,1); VirtualWriteRepeatAttribute(vw,REVERSE,1,1,13); WindowAssignToVirtual(w,vw,1,1); } The example above illustrates that the VirtualWriteRepeatAttribute() writes the REVERSE attribute 13 times starting at row 1, column 1 of the virtual window w. The return values for VirtualWriteRepeatAttribute() are the same as VirtualWriteStringAttr(). Page 140 The C Window Library Page 140 VirtualWriteRepeatCharacter() ----------------------------- The VirtualWriteRepeatCharacter() function writes a character a specified number of times to a virtual window. Here is a prototype: int VirtualWriteRepeatCharacter(WPOINTER w, int ch, int row, int col, int count) The count argument is the character to use. The count argument specifies the number of times to write the character ch to the virtual window starting at (row,col). Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); VirtualWriteRepeatCharacter(vw,'a',1,1,5); VirtualWriteRepeatCharacter(vw,'b',2,1,5); VirtualWriteRepeatCharacter(vw,'c',3,1,5); WindowAssignToVirtual(w,vw,1,1); } The example above illustrates that the VirtualWriteRepeatCharacter() writes the letter 'a', 'b', and 'c' 5 times on rows 1, 2, and 3 respectively. The return values for VirtualWriteRepeatCharacter() are the same as VirtualWriteString(). Page 141 The C Window Library Page 141 Formatted Write Functions ------------------------- Format String ------------- These functions write formatted output to virtual windows just like the printf() function. There are two functions that do this, namely VirtualPrintf() and VirtualPrintfAttr(). These functions use a format string that is similar to the format string found in printf(). For example, %d, %s, %lf, etc. and most of the escape sequences are supported. The list of escape sequences supported are as follows: \n - newline \t - tab \r - carriage return \x - hexadecimal Where Output is Placed ---------------------- The row and column of where the string will be written is determined by the virtual window's logical cursor. The logical cursor is advanced by both of these functions to one column position after the last character is printed. If you want to start at a particular row and column of the window, you must move the cursor yourself by calling the VirtualMoveCursor() function. This function is explained in the MOVING THE LOGICAL CURSOR section. When the virtual window is first initialized using VirtualInitialize(), the logical cursor is automatically moved to (1,1) of the virtual window. VirtualSetWrap() ---------------- With these functions, any text that will exceed the boundaries of the window will be wrapped to the next line. If the output will exceed the last row of the window, the window is automatically scrolled up by one line. This is the default action to take when characters exceed the right edge of the virtual window. If you want the output clipped instead of wrapped, you must set the virtual window's wrap flag using the VirtualSetWrap() function. The VirtualSetWrap() function sets the virtual window's wrap flag to either on or off. Here is the prototype: int VirtualSetWrap(VWPOINTER vw, int option) Page 142 The C Window Library Page 142 The second argument will be 0 if you want to turn the wrap flag off, or 1 if you want to turn it on. If the wrap flag is off, the output generated by VirtualPrintf() and VirtualPrintfAttr() will be terminated when the right edge of the window is reached. If the wrap flag is on, the output is wrapped to the next line when the right edge is reached. Unlike regular windows, the output is not scrolled if the last line of the virtual window is reached. You can set the wrap flag to a virtual window at any time. VirtualPrintf() -------------- The VirtualPrintf() function writes formatted output to the virtual window. Here is the prototype: int VirtualPrintf(VWPOINTER vw, char *format [,arg1,...]) The first argument is the virtual window. The second argument is a format string. The rest of the arguments are optional arguments that are written to the virtual window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; VWPOINTER vw; int i = 3; double j = 5.6; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,1,1); VirtualPrintf(vw,"3+2 is equal to %d\n",3+2); GET_KEY(); VirtualPrintf(vw,"i is equal to %d\nj is equal to %lf\n", i,j); } Page 143 The C Window Library Page 143 The above example illustrates how VirtualPrintf() is used to print formatted strings to a virtual window. The return values for VirtualPrintf() are the same as VirtualWriteString(). VirtualPrintfAttr() ------------------- The VirtualPrintfAttr() function writes formatted output to the virtual window. The difference between VirtualPrintf() and VirtualPrintfAttr() is that VirtualPrintfAttr() uses a video attribute specified as an argument. Here is the prototype: int VirtualPrintfAttr(VWPOINTER vw, int attr, char *format [,arg1,...]) The first argument is the virtual window. The second argument is the video attribute to use. The third argument is the format string. The rest of the arguments are optional arguments that are written to the virtual window. If the virtual window is NOATTRIBUTE, only the string is written to the window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; VWPOINTER vw; int i = 3; double j = 5.6; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,1,1); VirtualPrintfAttr(vw,REVERSE,"3+2 is equal to %d\n",3+2); GET_KEY(); VirtualPrintfAttr(vw,REVERSE, "i is equal to %d\nj is equal to %lf\n",i,j); } Page 144 The C Window Library Page 144 The above example illustrates how VirtualPrintfAttr() is used to print formatted strings. The return values for VirtualPrintfAttr() are the same as VirtualWriteStringAttr(). Page 145 The C Window Library Page 145 READING CHARACTERS AND ATTRIBUTES FROM VIRTUAL WINDOWS ------------------------------------------------------ With The C Window Library, you can read the contents of a virtual window into a character buffer. These functions provide the programmer with the contents of the virtual window at any time. The functions to perform this are VirtualReadAttributes(), VirtualReadCharacters() and VirtualReadCharAndAttr(). VirtualReadCharacters() ----------------------- The VirtualReadCharacters() function reads the characters from a virtual window into a buffer. Here is the prototype. int VirtualReadCharacters(VWPOINTER vw, char *buffer, unsigned row, unsigned col, unsigned length) The first argument is the virtual window. The second argument is the buffer to store the characters in. The third and fourth arguments are the (row,col) position in the virtual window to start reading from. The last argument is the number of characters to read. You must make sure that buffer has enough room to hold all of the characters read in. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; char buf[14] = {0}; /* Null all elements of buf */ main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(NOATTRIBUTE,10,80,NORM); VirtualWriteString(vw,"Hello World!!",1,1); VirtualReadCharacters(vw,buf,1,1,13); } The example above illustrates the use of VirtualReadCharacters(), which reads the virtual window's contents starting at (1,1). This happens to be the string "Hello World!!". Page 146 The C Window Library Page 146 If the length exceeds the right edge of the virtual window, VirtualReadCharacters() will read up to the right edge of the virtual window. If there are no errors, VirtualReadCharacters() returns NO_ERROR. If there are errors, VirtualReadCharacters() returns one of the following: BAD_V_WINDOW if the virtual window does not exist. V_WINDOW_BOUND if the row or column specified in the virtual window is out of bounds. VirtualReadAttributes() ---------------------- The VirtualReadAttributes() function reads the attributes from a virtual window into a buffer. Here is the prototype. int VirtualReadAttributes(VWPOINTER w, char *buffer, unsigned row, unsigned col, unsigned length) The first argument is the virtual window. The second argument is the buffer to store the attributes in. The third and fourth arguments are the (row,col) position in the virtual window to start reading from. The last argument is the number of attributes to read. If the virtual window is NOATTRIBUTE, nothing is read. You must make sure that buffer has enough room to hold all of the attributes read in. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; char buf[14] = {0}; /* Null all elements of buf */ main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(ATTRIBUTE,10,80,NORM); VirtualReadAttributes(vw,buf,1,1,13); /* Read attributes */ } Page 147 The C Window Library Page 147 The example above illustrates the use of VirtualReadAttributes(), which reads the virtual window's attribute contents starting at (1,1) of the virtual window. If the length exceeds the right edge of the virtual window, VirtualReadAttributes() will read up to the right edge of the virtual window. If there are no errors, VirtualReadAttributes() returns NO_ERROR. If there are errors, VirtualReadAttributes() returns one of the following: BAD_V_WINDOW if the virtual window does not exist. V_WINDOW_BOUND if the row or column specified in the virtual window is out of bounds. NO_ATTRIB if the virtual window is NOATTRIBUTE. VirtualReadCharAndAttr() ------------------------ The VirtualReadCharAndAttr() function reads character/attribute pairs from a virtual window into a buffer. Here is the prototype. int VirtualReadCharAndAttr(VWPOINTER w, char *buffer, unsigned row, unsigned col, unsigned length) The first argument is the virtual window. The second argument is the buffer to store the character/attribute pairs in. The third and fourth arguments are the (row,col) position in the virtual window to start reading from. The last argument is the number of character/attribute pairs to read. If the window is NOATTRIBUTE, nothing is read. You must make sure that buffer has enough room to hold all of the character/attribute pairs read in. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; char buf[27] = {0}; /* Null all elements of buf */ Page 148 The C Window Library Page 148 main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(ATTRIBUTE,10,80,NORM); VirtualWriteString(vw,"Hello World!!",1,1); VirtualReadCharAndAttr(vw,buf,1,1,13); } The example above illustrates the use of VirtualReadCharAndAttr(), which reads the virtual window's character/attribute contents starting at (1,1) of the virtual window. This happens to be the characters/attributes of the string "Hello World!!". If the length exceeds the right edge of the virtual window, VirtualReadCharAndAttr() will read up to the right edge of the virtual window. If there are no errors, VirtualReadCharAndAttr() returns NO_ERROR. If there are errors, VirtualReadCharAndAttr() returns one of the following: BAD_V_WINDOW if the virtual window does not exist. V_WINDOW_BOUND if the row or column specified in the virtual window is out of bounds. NO_ATTRIB if the virtual window is NOATTRIBUTE. Page 149 The C Window Library Page 149 REPOSITIONING THE VIEWPORT -------------------------- A viewport can be repositioned anywhere on the virtual window. This allows to view different parts of the virtual window. WindowPositionViewport() ------------------------ The WindowPositionViewport() function positions the viewport to a new location on the virtual window it is associated with. Here is the prototype: int WindowPositionViewport(WPOINTER w, unsigned row, unsigned col) The first argument is the viewport window. The second argument and third arguments are is the (row,col) position of the virtual window associated with w. This position will be where the upper left hand corner of the viewport's text area will be placed. Example: #include <stdio.h> #include <string.h> #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define FILENAMECHARS \ "25[A-Za-z0-9!@#$%/^&()+=_/-{}/[/]`~/.\\:]" VWPOINTER vw; /* virtual window pointer */ WPOINTER w; /* Window pointer */ char filename[26]; FILE *infile; /* input file handle */ main() { unsigned int i,j,row,col; WindowInitializeSystem(); WindowSaveInitial(0); /* set up a Type 0 virtual window */ vw = VirtualInitialize(NOATTRIBUTE,200,80,0); /* set up viewport window */ w = WindowInitialize(BORDER,1,1,78,12,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); Page 150 The C Window Library Page 150 /* read a file name */ read_file(); /* display file in viewport */ WindowAssignToVirtual(w,vw,1,1); row = col = 1; flush_keyboard_flag = TRUE; /* Set keyboard flush to TRUE */ while (1) { switch (GET_KEY()) /* Keep getting keys until ESCAPE key is hit */ { case UARROW: /* Move viewport up 1 line */ if (row > 1) WindowPositionViewport(w,--row,col); break; case DARROW: /* Move viewport down 1 line */ if (row < 189) WindowPositionViewport(w,++row,col); break; case LARROW: /* Move viewport left 1 line */ if (col > 1) WindowPositionViewport(w,row,--col); break; case RARROW: /* Move viewport right 1 line */ if (col < 69) WindowPositionViewport(w,row,++col); break; case ESC: /* End program */ close_all(); break; } } } read_file() /* Gets a filename and displays it in the window */ { int ch; unsigned r = 1, c = 1; filename[0] = 0; WindowWriteString(w,"Please enter a file name: ",1,1); WindowGetString(w,1,27,filename,'_',0,40,0,FILENAMECHARS); if ((infile = fopen(filename,"r")) == NULL) { WindowMoveCursor(w,3,1); WindowPrintf(w,"File name %s does not exist\n" "Press a key to continue", filename); GET_KEY(); close_all(); } else Page 151 The C Window Library Page 151 while(1) /* Read characters into virtual window */ { ch = fgetc(infile); if (feof(infile)) break; if (ch != '\n') VirtualWriteRepeatCharacter(vw,ch,r,c++,1); else { r++; c=1; } } fclose(infile); } close_all() { WindowClose(w,NOEFFECT); exit(0); } The above example reads in a text file and uses WindowPositionViewport() to move left, right, up, or down. There is no checking to see if you have scrolled past the end of the file. The read_file() function reads a file and copies each character in the file to the virtual window called vw. In the main program, the global variable flush_keyboard_flag, defined in the IMPORTANT GLOBAL VARIABLES section, is set to TRUE. When flush_keyboard is TRUE, the keyboard buffer is flushed before any incoming keystrokes are accepted. Otherwise the keyboard buffer is not flushed. In the while(1) loop of the main program, the constants UARROW, DARROW, LARROW, and RARROW, stands for the up, down, left, and the right arrow keys on the keypad, respectively. The constants UARROW, DARROW, LARROW, and RARROW are defined in keycodes.h. Depending on the key that is hit, the viewport is repositioned to point to a new row or column. The call to WindowPositionViewport() has three arguments. The first is the pointer to the viewport window, the second and the third are the row and the column of the virtual window to place the upper left hand corner of the viewport. There is minimal bounds checking in the above example, however you can enhance it by putting in more bounds checking and by implementing a page down, or page up function. Page 152 The C Window Library Page 152 If there are no errors, WindowPositionViewport() returns NO_ERROR. If there are errors, WindowPositionViewport() will return one of the following values: BAD_WINDOW if the viewport window does not exist. BAD_V_WINDOW if the viewport is pointing to a virtual window that does not exist. V_WINDOW_BOUND if the row and col arguments are out of bounds of the virtual window. Page 153 The C Window Library Page 153 SCROLLING THE VIEWPORTS ----------------------- Viewports can have its display scrolled left, right, up, or down using the WindowScrollViewport() function described below. WindowScrollViewport() --------------------- This functions scrolls the viewport specific number of characters. Here is the prototype: int WindowScrollViewport(WPOINTER w, unsigned num, int direction) The first argument is the viewport and the second argument is the number of characters to scroll. The last argument is the direction to scroll. This direction can be UP, DOWN, LEFT, or RIGHT. Example: #include <stdio.h> #include <string.h> #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define FILENAMECHARS \ "25[A-Za-z0-9!@#$%/^&()+=_/-{}/[/]`~/.\\:]" VWPOINTER vw; /* virtual window pointer */ WPOINTER w; /* Window pointer */ char filename[26]; FILE *infile; /* input file handle */ main() { unsigned int i,j,row,col; WindowInitializeSystem(); WindowSaveInitial(0); /* set up a Type 0 virtual window */ vw = VirtualInitialize(NOATTRIBUTE,200,80,0); /* set up viewport window */ w = WindowInitialize(BORDER,1,1,78,12,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); /* read a file name */ read_file(); Page 154 The C Window Library Page 154 /* display file in viewport */ WindowAssignToVirtual(w,vw,1,1); flush_keyboard_flag = TRUE; while (1) { switch (GET_KEY()) /* Keep getting keys until ESCAPE key is hit */ { case UARROW: /* Move viewport up 1 line */ WindowScrollViewport(w,1,UP); break; case DARROW: /* Move viewport down 1 line */ WindowScrollViewport(w,1,DOWN); break; case LARROW: /* Move viewport left 1 line */ WindowScrollViewport(w,1,LEFT); break; case RARROW: /* Move viewport right 1 line */ WindowScrollViewport(w,1,RIGHT); break; case ESC: /* End program */ close_all(); break; } } } read_file() /* Gets a filename and displays it in the window */ { int ch; unsigned r = 1, c = 1; filename[0]=0; WindowWriteString(w,"Please enter a file name: ",1,1); WindowGetString(w,1,27,filename,'_',0,40,0,FILENAMECHARS); if ((infile = fopen(filename,"r")) == NULL) { WindowMoveCursor(w,3,1); WindowPrintf(w,"File name %s does not exist\n" "Press a key to continue", filename); GET_KEY(); close_all(); } else while(1) /* Read characters into virtual window */ { ch = fgetc(infile); if (feof(infile)) break; if (ch != '\n') VirtualWriteRepeatCharacter(vw,ch,r,c++,1); else { r++; c=1; Page 155 The C Window Library Page 155 } } fclose(infile); } close_all() { WindowClose(w,NOEFFECT); exit(0); } The example above is the same as the example for the WindowPositionViewport() function, except that the call to WindowPositionViewport() is replaced with the appropriate WindowScrollViewport() call. For WindowScrollViewport(), the window is never scrolled if the scroll will result in the upper left hand corner of the viewport being out of bounds of the virtual window. For example, you cannot scroll left 1 character if the viewport is located at (1,1) of the virtual window, similarly you cannot scroll right if the virtual window has a maximum of 80 characters and the upper left hand corner of the viewport is situated at (1,80). The same restrictions apply for scrolling up and down. If there are no errors, all of the WindowScrollViewport() functions will return NO_ERROR. If there are errors, these functions will return the following value: V_WINDOW_BOUND if the scroll will cause the upper left hand position of the viewport to be out of bounds. Page 156 The C Window Library Page 156 WRITING VIRTUAL WINDOW CONTENTS TO A FILE ----------------------------------------- The C Window Library allows you to print the contents of a virtual window using the VirtualWriteTextToFile() function. VirtualWriteTextToFile() ------------------------ The VirtualWriteTextToFile() function allows you to print the contents of a virtual window to a file. Here is the prototype: int VirtualWriteTextToFile(VWPOINTER vw, char *filename, int mode) The first argument is the virtual window. The second argument is the file name. This file can be any of the DOS filenames ("con", "prn", "aux", etc.). The file specified by filename must be closed before calling VirtualWriteTextToFile(), and the file handle is automatically closed before exiting VirtualWriteTextToFile(). The last argument is the mode switch. If mode is 1, a newline ('\n') is written to the file after each line of the virtual window written to the file. If mode is 0, no newline character is written. When mode 0 is chosen, the file is open in binary mode, else it is open in text mode. Example: #include "window.h" VWPOINTER vw; char *filename = "wintext"; char *filename2 = "wintext2"; main() { int i; WindowInitializeSystem(); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); for (i=1;i<=10;i++) VirtualWriteString(vw,"Hello World!!",i,1); VirtualWriteTextToFile(vw,filename,1); /* use newlines */ VirtualWriteTextToFile(vw,filename2,0); /* no newlines */ } The example above illustrates two calls to VirtualWriteTextToFile(). The first call writes the contents of the virtual window vw to a file called "wintext". Note that the mode parameter for the first call is 1. This will cause '\n' to be written to the file for each line of the Page 157 The C Window Library Page 157 virtual window. The second call writes the virtual window text to a file call "wintest2", with the mode parameter being 0 (no '\n'). Please note that VirtualWriteTextToFile() does not check if the file already exists, so be careful that you do not replace files that are important to you. If there are no errors, VirtualWriteTextToFile() returns NO_ERROR. If there are errors, VirtualWriteTextToFile() will return one of the following: BAD_V_WINDOW if the virtual window does not exist. FILE_CANT_OPEN if the file specified by filename cannot be open. FILE_CANT_CLOSE if the file specified by filename cannot be closed. Page 158 The C Window Library Page 158 MOVING THE LOGICAL CURSOR ------------------------- You can move and get the position of the logical cursor in a virtual window. VirtualMoveCursor() ------------------- The VirtualMoveCursor() function moves a virtual window's logical cursor to a new location. Here is the prototype: int VirtualMoveCursor(VWPOINTER vw, unsigned row, unsigned col) The first argument is the virtual window, and the second and third arguments denote the new (row,col) position of the logical cursor. Example: #include "window.h" VWPOINTER vw; main() { int i; WindowInitializeSystem(); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); VirtualMoveCursor(vw,10,10) /* Moves the logical cursor to row 10, column 10 of the virtual window */ } If there are no errors, VirtualMoveCursor() returns NO_ERROR. If there are errors, VirtualMoveCursor() returns one of the following values: BAD_V_WINDOW if the virtual window does not exist. V_WINDOW_BOUND if either the row or column specified is out of bounds. VirtualGetCursorPosition() -------------------------- The VirtualGetCursorPosition() function gives the current row and column of the cursor in a virtual window. Here is the prototype: Page 159 The C Window Library Page 159 int VirtualGetCursorPosition(VWPOINTER vw, unsigned *row, unsigned *col) The row and col arguments are pointers to unsigned integers that will contain the row and column of the cursor after VirtualGetCursorPosition() is called. Example: #include "window.h" VWPOINTER vw; main() { unsigned row,col; WindowInitializeSystem(); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); VirtualMoveCursor(vw,7,4); VirtualGetCursorPosition(vw,&row,&col); } If there are no errors, VirtualGetCursorPosition() returns NO_ERROR. If there are errors, VirtualGetCursorPosition() returns the following value: BAD_V_WINDOW if the window does not exist. Page 160 The C Window Library Page 160 CLEARING VIRTUAL WINDOWS ------------------------ The C Window Library contains functions that clears the entire virtual window, or clears defined rectangular regions of the virtual window. VirtualClear() -------------- The VirtualClear() function clears an entire virtual window to spaces. Here is the prototype: int VirtualClear(VWPOINTER vw) The only argument is the virtual window to clear. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; WPOINTER w; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,20,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,1,1); for (i=1;i<=10;i++) VirtualWriteString(vw,"Hello World!!",i,1); GET_KEY(); VirtualClear(vw); } If there is no error, VirtualClear() returns NO_ERROR. If there is an error, VirtualClear() returns the following values: BAD_V_WINDOW if the virtual window does not exist. Page 161 The C Window Library Page 161 VirtualClearAttr() ------------------ The VirtualClearAttr() function works the same way as the VirtualClear() function except that an attribute is specified. Here is the prototype: int VirtualClearAttr(VWPOINTER vw, int attr) The second argument is the video attribute to use. If the virtual window is NOATTRIBUTE, this function only clears the text. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; VWPOINTER vw; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,1,1); for (i=1;i<=10;i++) VirtualWriteString(vw,"Hello World!!",i,1); GET_KEY(); VirtualClearAttr(vw,REVERSE); } The return values for VirtualClearAttr() are the same as VirtualClear(), except for the following error: NO_ATTRIB if the virtual window is NOATTRIBUTE. VirtualClearRegion() ------------------- The VirtualClearRegion() function clears a region of a virtual window. To use the VirtualClearRegion() function, you must describe the rectangular region to clear. Here is the prototype: int VirtualClearRegion(VWPOINTER vw, unsigned urow, unsigned ucol, unsigned lrow, unsigned lcol) Page 162 The C Window Library Page 162 where (urow,ucol) describes the upper left of the rectangle and (lrow,lcol) is the lower right of the virtual window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; VWPOINTER vw; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,1,1); for (i=1;i<=10;i++) VirtualWriteString(vw,"Hello World!!",i,1); GET_KEY(); VirtualClearRegion(vw,4,4,8,15); } The VirtualClearRegion() call will clear the region described by the rectangular coordinates (4,4) and (8,15). If there is no error, VirtualClearRegion() returns NO_ERROR. If there is an error, the VirtualClearRegion() function will return the following values: BAD_V_WINDOW if the VWPOINTER vw does not exist. V_WINDOW_BOUND if the rectangular region defined is out of bounds of the virtual window. VirtualClearRegionAttr() ------------------------ The VirtualClearRegionAttr() function works the same as the VirtualClearRegion() function, except that a video attribute is specified. Here is the prototype: int VirtualClearRegionAttr(VWPOINTER vw, unsigned urow, unsigned ucol, unsigned lrow, unsigned lcol, int attr) Page 163 The C Window Library Page 163 The attr argument is a video attribute to use to clear the region. If the virtual window is NOATTRIBUTE, the attribute argument is ignored. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) WPOINTER w; VWPOINTER vw; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,1,1); for (i=1;i<=10;i++) VirtualWriteString(vw,"Hello World!!",i,1); GET_KEY(); VirtualClearRegionAttr(vw,4,4,8,15,REVERSE); } The VirtualClearRegionAttr() call will clear the region described by the rectangular coordinates (4,4) and (8,15) using the video attribute defined by the constant REVERSE. The VirtualClearRegionAttr() returns the same values as VirtualClearRegion() with an additional error condition: NO_ATTRIB if the virtual window is NOATTRIBUTE. Page 164 The C Window Library Page 164 FREEZING VIEWPORTS ------------------ You can temporarily suspend or 'freeze' a viewport window from displaying updates to the virtual window. This is good if there is data being written to the virtual window which takes a long time to generate. The viewport can be frozen when the information is being written, and unfrozen when the writing of the data is terminated. WindowFreeze() -------------- The WindowFreeze() function suspends or resumes displaying of virtual window updates on a viewport window. Here is the prototype: int WindowFreeze(WPOINTER w, int option) The first argument is the viewport window, and the second argument is the option flag. If this flag is 0, the window is unfrozen, i.e. the window will display virtual window updates. If it is 1, the window will suspend virtual window updates from being displayed. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; WPOINTER w; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,10,80,NORM); WindowOpen(w); WindowAssignToVirtual(w,vw,1,1); WindowDisplay(w,1,NOEFFECT); /* Freeze Viewport */ WindowFreeze(w,1); for (i=1;i<=10;i++) { delay(1000); VirtualPrintf(vw,"Line %d\n",i); } /* Unfreeze window */ WindowFreeze(w,0); Page 165 The C Window Library Page 165 GET_KEY(); /* Now try with window always displaying data */ VirtualClear(vw); for (i=1;i<=10;i++) { delay(1000); VirtualPrintf(vw,"Line %d\n",i); } } The above program first freezes the viewport w with the first call to WindowFreeze(). Then text is written slowly to the virtual window vw. This text is not displayed until the window is unfrozen again with the second call to WindowFreeze(). Everything is reset and the writing of the text to the virtual window is done again, but this time the viewport is always displaying virtual window updates, even when the text is being written to the virtual window. The delay() function is discussed in the TIMED DELAYS section. If there is no error WindowFreeze() returns NO_ERROR. If there are errors, WindowFreeze() returns one of the following values: BAD_WINDOW if the viewport window does not exist. BAD_V_WINDOW if the virtual window that the viewport is displaying does not exist. Page 166 The C Window Library Page 166 DISPOSING OF VIRTUAL WINDOWS ---------------------------- The last step is to dispose of the virtual window. The function to do this is the VirtualFree() function. VirtualFree() ------------- The VirtualFree() function frees all the memory allocated to the virtual window and destroys the virtual window pointer. Here is the prototype: int VirtualFree(VWPOINTER vw, int hideflag, int effect) The first argument is the virtual window. The second argument is a flag that determines whether any viewports displaying the virtual window should be hidden. If this argument is 1, all viewports displaying the virtual window is hidden. If the argument is 0, all viewports are cleared, but not hidden. The third argument is the special effect to use when hiding the viewports. This argument is ignored if hideflag is 0. For a list of special effects, refer to the DISPLAYING WINDOWS section. Once VirtualFree() is called you must not use the VWPOINTER again unless you assign it to another virtual window, or create a new virtual window. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) VWPOINTER vw; /* virtual window pointer */ WPOINTER w1, w2; main() { WindowInitializeSystem(); WindowSaveInitial(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); w1 = WindowInitialize(BORDER,1, 1,20,12,NORM,NORM, SINGLEBOX); w2 = WindowInitialize(BORDER,13,1,20,10,NORM,NORM, DOUBLEBOX); WindowOpen(w1); WindowOpen(w2); WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); VirtualWriteString(vw,"This is a string",1,1); WindowAssignToVirtual(w1,vw,1,1); WindowAssignToVirtual(w2,vw,1,1); Page 167 The C Window Library Page 167 GET_KEY(); VirtualFree(vw,1,NOEFFECT); } If there are no errors, VirtualFree() returns NO_ERROR. If there are errors, VirtualFree() returns the following value: BAD_V_WINDOW if the virtual window does not exist. Page 168 The C Window Library Page 168 INTRODUCTION TO MENU SYSTEM --------------------------- Menu systems are important entities in any program. The C Window Library has functions that create popup, pull-down, and bar menus. The popup menus are scrollable menus with a limit of 65,535 selections. The bar menus can have any number of entries. As of this version, the bar menus are not scrollable, although there will be an implementation of scrolling bar menus in a future version. The pull-down menus are a combination of popup and bar menus. You can change entries, hide entries, use hotkeys to invoke a menu entry, and many more things. Menu Manager ------------ The menu manager is the code in The C Window Library that handles moving the highlight bar in the menu, calling the menu functions when they are selected, keeps tracks of available entries, and other functions that keep track of the menu when selections are made. Necessary "include" files ------------------------- To use the menu system in your program, you must include the "menu.h" file supplied. This file automatically includes the "window.h" file, therefore you do not have to include "window.h" when you use "menu.h". Page 169 The C Window Library Page 169 POP-UP MENUS ------------ Description ----------- A popup menu is a vertical menu with a list of entries that are selected by placing a highlight bar on the entry and pressing return, or by invoking the function by using a hotkey. Pop-up menus can be scrollable, in other words, if there are more entries than can be displayed in the window, the menu will scroll through the rest of the selections. You can have up to 65,535 selections in the popup menu. Here is a partial list of the various options you can have with popup menus: * Highlight bar wrapping - wrap highlight bar to first or last option when there are no more selections. * Static Menus - menu remains on the screen when entry is selected. * Perpetual Menus - menu remain on the screen regardless of whether the PopupSelectMenu() function (explained later) is called or not. * Hidden (Unavailable) entries - You can make an entry in the popup menu unavailable or available at any time. * Color scheme of the menu - You can customize the color of the highlight bar, the hotkey letters, hidden entries, etc. * Change entry names - You can safely change the names displayed in the menu at any time. * Use a mouse to select menu entries. Windows and Virtual Windows --------------------------- Pop-up menus use virtual windows to write menu selections, and use normal windows to display the selections. This method of using virtual windows enables the menu manager to scroll through the menu selections if the window is not tall enough to display all of the selections. Page 170 The C Window Library Page 170 CREATING POP-UP MENUS --------------------- The POPUP_MENU_ENTRY structure ------------------------------ The two most important parts of the popup menu are the POPUP_MENU_ENTRY structure and the POPUP_MENU_PTR structure. The POPUP_MENU_ENTRY structure is the first step in creating a popup menu and is discussed here. Each entry in the popup menu has its own POPUP_MENU_ENTRY structure associated with it. The layout of this structure is as follows: char *entry_name -- This is the string that is displayed in the popup virtual window. unsigned row -- Row in the virtual window to display entry_name. char hotkey_letter -- This is a character in entry_name that is highlighted from the rest of the characters in entry_name. This letter will automatically invoke the menu function associated with entry_name. unsigned ext_hotkey -- This is a secondary hotkey. The difference between hotkey_letter and ext_hotkey is that ext_hotkey can handle keys that are not ASCII keys (the F keys, Alt and Ctrl key combinations, etc.). int (*func)() -- Pointer to function that is invoked when option is selected. An array of POPUP_MENU_ENTRY's are needed to create all of the entries on the popup menu. The order of the array elements determine the order of how they are placed in the virtual window. A code sample to create an array of POPUP_MENU_ENTRY's would be as follows: #include "menu.h" int menu_func(); POPUP_MENU_ENTRY menu_items[] = { " Load F3", /* entry name */ 1, /* row number */ 'L', /* hotkey */ Page 171 The C Window Library Page 171 F3, /* secondary hotkey */ menu_func, /* function to call if chosen */ /* now do rest of the popup entries */ " Pick Alt-F3",2, 'P',ALTF3,menu_func, " New" ,3, 'N',0,menu_func, " Save F2",4, 'S',F2,menu_func, " Write to ",5, 'W',0,menu_func, " Directory ",6, 'D',0,menu_func, " Change Dir" ,7, 'C',0,menu_func, " OS shell" ,8, 'O',0,menu_func, " Quit Alt-X" ,9,'Q',ALTX,menu_func, /* Terminate with a CWL_NULL and 0 */ CWL_NULL,0}; The first include file, menu.h, is must be included in each source file that calls menu functions. As you can see, there is an array of POPUP_MENU_ENTRY's, namely menu_items. Each entry consists of an entry name, row number, hotkey letter, secondary hotkey, and a function to call when the entry is selected. The list of POPUP_MENU_ENTRY's MUST be terminated by a CWL_NULL entry name, and a row number of 0. If this rule is violated, the menu manager will not know where the last entry is, and will cause chaos when the program is run. There is an alternate method of creating the array of POPUP_MENU_ENTRY's. Later on we will discuss creating these entries dynamically. Defining Hotkeys ---------------- The hotkey_letter defined in the POPUP_MENU_ENTRY structure must match one of the letters in its corresponding entry_name. For example, " Load F3", has the hotkey_letter defined as 'L'. Since 'L' matches the first letter in " Load F3", the first 'L' in " Load F3" is highlighted. If there is no match, or if the hotkey_letter is 0, there is no hotkey associated with this option. When the menu is displayed, either the 'l' or 'L' will be accepted as a valid selection to the entry " Load F3". If there is a POPUP_MENU_ENTRY with the same hotkey letter as another POPUP_MENU_ENTRY, the POPUP_MENU_ENTRY closest to the first entry is chosen. Page 172 The C Window Library Page 172 The ext_hotkey is used if the hotkey cannot be defined as a single character, or if you want another hotkey definition. In the above example, the " Load F3" entry_name has an ext_hotkey of F3 (defined in keycodes.h). If the F3 key is pressed, the function menu_func() is automatically invoked. If the ext_hotkey letter is 0, there is no ext_hotkey defined. If there is a POPUP_MENU_ENTRY with the same ext_hotkey as another POPUP_MENU_ENTRY, the POPUP_MENU_ENTRY closest to the first entry is chosen. Assigning the function to perform --------------------------------- The func() member is the function that is performed when its corresponding entry_name is chosen. This is the first step in completing the total popup menu. Once the array of POPUP_MENU_ENTRY's is created the next step is to define the colors for each element of the popup menu. Coloring Popup Menus -------------------- An array of unsigned integers is used to define the color scheme of the popup menu. Each element of this array stands for a certain area of the popup menu. Here is a list of array positions and what they stand for. Position Constant -------- ENTRYCOLOR -- color of the text area of the viewport window. BORDERCOLOR -- color of the border of the viewport window. HOTKEYCOLOR -- color of the hotkey letter. HIGHLIGHTCOLOR -- color of the highlight bar. UNAVAILCOLOR -- color of the unavailable entries. Position ENTRYCOLOR of the array defines the color of the text area of the viewport window. This in turn defines the color of each entry_name of all of the POPUP_MENU_ENTRY's. Position BORDERCOLOR defines the color of the border of the viewport window. As was stated above, the menu is written to a virtual window, and a viewport is used to display the menu Page 173 The C Window Library Page 173 entries. If the viewport window does not have a border, this attribute is ignored. Position HOTKEYCOLOR defines the color to use for the hotkey letter. In the above example, the 'L', 'P', 'N', etc. of each respective entry_name is displayed using this color. Position HIGHLIGHTCOLOR defines the color used for the highlight bar. This bar is moved up and down when the user is making a selection. Position UNAVAILCOLOR defines the color of the unavailable menu entries. Whenever a menu entry is unavailable, the entry_name string displayed takes on this color. Colors can be created by using the CREATE_VIDEO_ATTRIBUTE(). A code sample to create the colors is as follows: #include "menu.h" unsigned int menu_colors[5]; main() { {... code ...} menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white); menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white); menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(blue,white); menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,cyan); menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); /* rest of the program */ } Creating popup menu entries dynamically --------------------------------------- You can create POPUP_MENU_ENTRY's dynamically, instead of defining a pre-determined array of POPUP_MENU_ENTRY's explained previously. Here is an example: Usual method: ------------ POPUP_MENU_ENTRY menu_items[] = { " Load F3", /* entry name */ 1, /* row number */ 'L', /* hotkey */ Page 174 The C Window Library Page 174 F3, /* secondary hotkey */ menu_func, /* function to call if chosen */ " Pick Alt-F3",2, 'P',ALTF3,menu_func, " New" ,3, 'N',0,menu_func, " Save F2",4, 'S',F2,menu_func, " Write to ",5, 'W',0,menu_func, " Directory ",6, 'D',0,menu_func, " Change Dir" ,7, 'C',0,menu_func, " OS shell" ,8, 'O',0,menu_func, " Quit Alt-X" ,9,'Q',ALTX,menu_func, /* Terminate with a CWL_NULL and 0 */ CWL_NULL,0}; Dynamic Method -------------- #include "menu.h" #define NUMENTRIES 9 POPUP_MENU_ENTRY_PTR menu_array; /* Notice that we have a pointer to what will be an array of POPUP_MENU_ENTRY's */ POPUP_MENU_PTR p; main() { WindowInitializeSystem(); /* Initialize with at least number of total entries */ menu_array = PopupAllocate(NUMENTRIES); /* Call function to create entries in menu_array sequentially */ PopupCreateEntry(menu_array, /* POPUP_MENU_ENTRY pointer */ 1, /* entry number */ /* The rest of the arguments are just like the old method */ " Load F3", /* menu string */ 1, /* row number */ 'L', /* hotkey letter */ F3, /* secondary hotkey */ menu_func); /* function to perform */ /* do rest of the entries */ PopupCreateEntry(menu_array,2," Pick Alt-F3",2,'P',ALTF3, menu_func); Page 175 The C Window Library Page 175 PopupCreateEntry(menu_array,3," New",3,'N',0,menu_func); PopupCreateEntry(menu_array,4," Save F2",4,'S',F2, menu_func); PopupCreateEntry(menu_array,5," Write to ",5,'W',0, menu_func); PopupCreateEntry(menu_array,6," Directory ",6,'D',0, menu_func); PopupCreateEntry(menu_array,7," Change Dir ",7,'C',0, menu_func); PopupCreateEntry(menu_array,8," OS Shell ",8,'O',0, menu_func); PopupCreateEntry(menu_array,9," Quit Alt-X ",9,'Q',ALTX,0, menu_func); /* end all of the menu entries */ PopupEntryEnd(menu_array,NUMENTRIES); /* create menu */ p = PopupCreateMenu(menu_array, ... /* other arguments */); /* ... */ /* Dispose of menu entries created */ PopupDeallocate(menu_array); } The difference between the above method and the method used to globally initialize an array are the following: 1) The variable type for menu_array is POPUP_MENU_ENTRY_PTR, not POPUP_MENU_ENTRY as the normal method would have done. 2) You must call the PopupAllocate() function to allocate space for the number of entries desired. If you do not call PopupAllocate(), you will surely get a memory overwrite error. The return value to PopupAllocate() must be assigned to a POPUP_MENU_ENTRY_PTR, as the above example shows. The array of menu entries are allocated from the heap at runtime, as opposed to the static method which sets up the memory scheme at link time. 3) The next thing you must do is to fill in the entry information by calling the PopupCreateEntry() function. The first argument to the PopupCreateEntry() function is the POPUP_MENU_ENTRY_PTR. The second argument is the entry number to assign this information to. The rest of Page 176 The C Window Library Page 176 the arguments are the same order as the usual method i.e. menu string, row, hotkey, etc. PopupCreateEntry() is called for each field desired. 4) The PopupEndEntry() function must be called to terminate the list of entries. The first argument is the POPUP_MENU_ENTRY_PTR, and the second argument is the total number of entries defined. 5) You should call PopupDeallocate() to free the memory assigned to the array of menu_entries. The only argument to PopupDeallocate() is the POPUP_MENU_ENTRY_PTR. Only call PopupDeallocate() after you have called PopupMenuFree() or any function that disposes of the POPUP_MENU_PTR. All of these functions except for PopupAllocate() have no return values. The PopupAllocate() function returns a POPUP_MENU_ENTRY_PTR if successful, and a null pointer if unsuccessful. The advantages of using the above method over the first method is that POPUP_MENU_ENTRY's are dynamically allocated rather than statically declared at compile time. This allows the programmer to create loops to set up the entries, read entry information from a file and assign this info to a POPUP_MENU_ENTRY, etc. You could also do the following: #include "menu.h" #define NUMENTRIES 9 POPUP_MENU_ENTRY menu_array[NUMENTRIES+1]; /* We must have at least 1 more than the number of entries */ POPUP_MENU_PTR p; main() { /* ... */ /* Call function to create entries in menu_array sequentially */ PopupCreateEntry(menu_array,1," Load F3",1,'L',F3, menu_func); PopupCreateEntry(menu_array,2," Pick Alt-F3",2,'P',ALTF3, menu_func); PopupCreateEntry(menu_array,3," New",3,'N',0,menu_func); Page 177 The C Window Library Page 177 PopupCreateEntry(menu_array,4," Save F2",4,'S',F2, menu_func); PopupCreateEntry(menu_array,5," Write to ",5,'W',0, menu_func); PopupCreateEntry(menu_array,6," Directory ",6,'D',0, menu_func); PopupCreateEntry(menu_array,7," Change Dir ",7,'C',0, menu_func); PopupCreateEntry(menu_array,8," OS Shell ",8,'O',0, menu_func); PopupCreateEntry(menu_array,9," Quit Alt-X ",9,'Q',ALTX,0, menu_func); /* end all of the menu entries */ PopupEntryEnd(menu_array,NUMENTRIES); } The method above does not call PopupAllocate() because the number of entries was already determined and an array was already set up at compile time. PopupCreateEntry() is called for each menu entry as before, and PopupEntryEnd() is called to terminate the menu entries. To use this method, you must declare an array of menu entries with at least one more than the desired number of entries. Also note that PopupDeallocate() MUST NOT be called because the array of menu entries was not created with PopupAllocate(). Page 178 The C Window Library Page 178 PopupCreateMenu() function -------------------------- Now that you have created the POPUP_MENU_ENTRY's, and defined the color scheme, it is time to wrap all of these loose ends in one package. The next step is to call the PopupCreateMenu() function. This function combines all of the POPUP_MENU_ENTRY's, the colors you have defined, and other information into one entity called a POPUP_MENU_PTR. A POPUP_MENU_PTR is a pointer to a popup menu structure. Just like a WPOINTER is a pointer to a window, a POPUP_MENU_PTR is used to reference the popup menu. A prototype of the call to PopupCreateMenu() is as follows: POPUP_MENU_PTR PopupCreateMenu(POPUP_MENU_ENTRY *p, unsigned *color, int row, int col, int height, unsigned options, WPOINTER (*wfunc)(), VWPOINTER (*vfunc)()) To illustrate how to use this call, let's use the POPUP_MENU_ENTRY's and colors created in the previous examples: #include "menu.h" int menu_func(); POPUP_MENU_ENTRY menu_items[] = { " Load F3", 1,'L',F3,menu_func, " Pick Alt-F3",2, 'P',ALTF3,menu_func, " New" ,3, 'N',0,menu_func, " Save F2",4, 'S',F2,menu_func, " Write to ",5, 'W',0,menu_func, " Directory ",6, 'D',0,menu_func, " Change Dir" ,7, 'C',0,menu_func, " OS shell" ,8, 'O',0,menu_func, " Quit Alt-X" ,9,'Q',ALTX,menu_func, CWL_NULL,0}; unsigned int menu_colors[5]; POPUP_MENU_PTR p; main() { WindowInitializeSystem(); /* define colors */ menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white); menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white); menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(blue,white); menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,cyan); Page 179 The C Window Library Page 179 menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); /* create a POPUP_MENU_PTR */ WindowSaveInitial(0); /* Save initial screen */ p = PopupCreateMenu(menu_items,menu_colors, 10,10,9,NO_POPUP_OPTIONS, WNULLFN,VWNULLFN); /* rest of the code */ } In the example above there are two function calls that must be done before calling PopupCreateMenu(). The first mandatory function is WindowInitializeSystem(). The other function must be WindowSaveInitial() The WindowInitializeSystem() function must be called to initialize global variables used by the menu manager. The WindowSaveInitial() function is a mandatory function because the PopupCreateMenu() function creates windows and virtual windows and assumes that the base screen has been saved. The example above declares the variable p to be a POPUP_MENU_PTR. This POPUP_MENU_PTR is going to be used to reference the popup menu throughout the program. The first argument to PopupCreateMenu() is a pointer to the first POPUP_MENU_ENTRY. In the above example, menu_items is a pointer to the first POPUP_MENU_ENTRY. The second argument is a pointer to the array of colors. In our example, menu_colors is our array of colors. The third and fourth arguments denote the row and column to place the upper left hand corner of the popup menu window. The fifth argument is the height of the popup menu window. If the height of the window will not accommodate all of the menu items, the menu manager will scroll the window so that the entries that are obscured come into view. The sixth argument are various popup menu options that are assigned to the popup menus which are defined below. Popup Menu Options ------------------ By default the menu manager assumes the following things: 1) The highlight bar does not wrap if the user wants to move the bar past the last entry, or before the first entry. Page 180 The C Window Library Page 180 2) The menu will be hidden from the screen when a selection is made and will reappear when control is returned to the menu manager. 3) A function is automatically invoked when the hotkey is pressed instead of calling a user-defined function which will tell the menu manager whether the menu entry is to be executed. 4) The popup menu window is hidden when the menu manager returns control to the calling function. 5) The highlight bar will skip unavailable entries. 6) The menu manager does not recognize enhanced keys (F11, F12, etc.). 7) The mouse will not be used to move the highlight bar. 8) Scroll characters will not be displayed on the popup window. The scroll characters allow the user to scroll through the options with a mouse. The last two options are only available if you have a Microsoft compatible mouse, and the mouse is activated. If the constant NO_POPUP_OPTIONS is used, the assumptions above are used. If you want to override the above defaults, use the following options: Option Name Definition ----------- ---------- POPUPWRAP Highlight bar wrapping. POPUPSTATIC Do not hide menu when selection is made. POPUPCONFIRM Confirmation when selection is made via hotkey. POPUPDISPLAY Display menu even after exit. POPUPOVERRIDE Accept Unavailable entries. POPUPENHANCEDKEY Recognize enhanced keys. POPUPMOUSE Use the mouse to select entries. POPUPMOUSESCROLL Use the mouse to scroll through entries by placing mouse on hotspots. As was stated before, the last two options, POPUPMOUSE and Page 181 The C Window Library Page 181 POPUPSCROLLCHARS, can only be used if you have a mouse installed, and the mouse is activated. More information on these two options is given in the USING A MOUSE section. By turning the above options "on" the following is assumed: 1) POPUPWRAP will wrap the highlight bar if the user wants to move the bar past the last entry or before the first entry. 2) POPUPSTATIC will not hide the menu when a selection is made. 3) POPUPCONFIRM will call a user-defined function before invoking the hotkey that was selected. This function will then return an integer back to the menu manager informing whether the function selected should be invoked, or the request should be rejected. There is more information on this option in the SETTING OPTIONS IN POPUP MENUS section below. 4) POPUPDISPLAY will not hide the popup window when the menu manager returns control to the calling function. 5) POPUPOVERRIDE will make the menu manager accept unavailable entries. 6) POPUPENHANCEDKEY will inform the menu manager that enhanced keys will be recognized. 7) POPUPMOUSE allows the use of a mouse to make selections. 8) POPUPMOUSESCROLL allows the user to scroll through the options using a mouse. You can also set multiple options by using a bitwise OR (|). For example: p = PopupCreateMenu(arg1,arg2,arg3,arg4,arg5, POPUPWRAP | POPUPSTATIC | POPUPCONFIRM,arg7,arg8) will set options POPUPWRAP, POPUPSTATIC, and POPUPCONFIRM defined above. The last two arguments to PopupCreateMenu() are defined in the next sections. Default Popup Window and Creating Your own Windows -------------------------------------------------- The sixth argument to the PopupCreateMenu() function is a pointer to a function that will open a popup menu window. If this is a NULL function pointer (WNULLFN), the menu manager Page 182 The C Window Library Page 182 will create a window. For most applications, the window that the menu manager will create is adequate. The menu manager uses these defaults when making the popup window: - A bordered window with the border consisting of single lines (SINGLEBOX). - The width of the window is determined by the longest entry_name in the POPUP_MENU_ENTRY's. If you want to create your own popup menu window, your function must return a WPOINTER. Inside your function you must create and open a window using WindowInitialize() and WindowOpen(). For most applications, you do not have to display the window, instead the menu manager can do the displaying and hiding of the windows. Here is an example of creating your own custom window function: #include "menu.h" /* Other includes and menu stuff */ WPOINTER my_open(); POPUP_MENU_PTR p; main() { /* Other code */ p = PopupCreateMenu(menu_items,menu_colors,10,10,9, my_open,WNULLFN); /* More code */ } WPOINTER my_open() { WPOINTER w; w = WindowInitialize(NOBORDER,1,1,20,10,BLACKONWHITE, BLACKONWHITE,""); WindowOpen(w); return w; /* May be WIN_NULL_PTR, but must return to PopupCreateMenu() */ } The example above lets the menu manager know that the window creation function is a user written function called my_open. The row, column and height arguments (arguments 3, 4 and 5) of PopupCreateMenu() will be ignored when using a custom window function. The row, column and height parameters used to create the window in the call to WindowInitialize() in my_window() will take precedence over the arguments 3, 4, and 5 used in PopupCreateMenu(). Page 183 The C Window Library Page 183 Default Virtual Window and Creating Your own Virtual Windows --------------------------------- The last argument to PopupCreateMenu() is a pointer to a function that will return a VWPOINTER. This function creates the virtual window used to write the menu entries. If this is a NULL function pointer (VWNULLFN), the menu manager will create the virtual window. If you do specify a function, your virtual window must have enough rows to hold all of the POPUP_MENU_ENTRY's, and be wide enough to hold the length of the longest entry_name. When the menu manager creates the virtual window, the following defaults are assumed: a) the virtual window has its own video attributes. b) Must be large enough to hold all the POPUP_MENU_ENTRY's. Your custom function should create a virtual window which follows both rules. You must also make sure that the virtual window was created and opened successfully. If the virtual window cannot be created because of a lack of memory, you must return the NULL virtual window pointer instead. From there, PopupCreateMenu() will do any cleaning up and will return with a null POPUP_MENU_PTR. My last advice when calling the PopupCreateMenu() function is that your best bet is to let the menu manager create the windows and virtual windows. You can always resize, change border types, etc. later on. Since virtual window's are not visible anyway, it makes sense to let the menu manager determine how the virtual window should be created. The last two arguments to the PopupCreateMenu() function are for those programmers who need full control of window, and virtual window management. Accessing Popup Windows and Virtual Windows ------------------------------------------- After calling the PopupCreateMenu() function, you can access the popup window by using the POPUP_WINDOW() macro. In the above example, p is the POPUP_MENU_PTR and the value of POPUP_WINDOW(p) is a pointer to the popup menu's window. If you want to change borders move, slide, or anything you can do with normal windows, you must access the popup window in this way. For example, if you want to change the border of the popup window you would do the following: Page 184 The C Window Library Page 184 p = PopupCreateMenu(... /* other arguments */ ) WindowDrawBorder(POPUP_WINDOW(p),DOUBLEBOX); The example calls WindowDrawBorder() to change the border of the popup window. If you want to write information to the virtual window created by the PopupCreateMenu() function, you can access the virtual window by using the POPUP_VIRTUAL_WINDOW() macro. By accessing the popup-menu's virtual window, you can read and write to and from the virtual window. This is very useful if you want to draw horizontal lines in your menu. An example would be as follows: char *h = "----------------------"; /* ...Some code... */ p = PopupCreateMenu(menu_items,menu_colors,10,10,9, WNULLFN,VWNULLFN); VirtualWriteString(POPUP_VIRTUAL_WINDOW(p),h,8,1); Warnings -------- Do not call WindowFree(), WindowClose() or VirtualFree() on the window or the virtual window of the popup menu. The menu manager will call these functions when PopupMenuFree() is called. If you close the popup window, or the virtual window on an active menu, the menu manager will assume that these windows still exist. Doing so will almost guarantee your application will bomb out. Return Values for PopupCreateMenu() ----------------------------------- If there are no errors, PopupCreateMenu() returns a valid POPUP_MENU_PTR pointer. If there is an error when PopupCreateMenu() is called, a null POPUP_MENU_PTR is returned. Here are the possible reasons why an error has occurred: 1) There is not enough memory to allocate for the POPUP_MENU_PTR or its internal data structures. 2) There is not enough memory to allocate for the popup window. 3) There is not enough memory to allocate for the virtual window. 4) The popup window's size was invalid. Page 185 The C Window Library Page 185 Problems 1,2, and 3 all are caused by a lack of heap memory. Problem 4 stems from having invalid parameters in the PopupCreateMenu(). The arguments that are suspect are the third, fourth, and fifth arguments. To remedy this problem, adjust these arguments such that the window can fit on the screen. For all of the above conditions, you can get the actual error code by checking the value of the global integer window_error_code. If window_error_code is equal to NO_HEAP_MEM, then condition 1, 2, or 3 has occurred. If it is equal to BAD_WINDOW_SIZE, then condition 4 has occurred. If you have a custom window or virtual window opening function, it is your responsibility to check the error conditions that may occur, and return correct values or null pointers if you cannot rectify the error in your custom routine. Here is an example: Example: int status; POPUP_MENU_PTR p; p = PopupCreateMenu(...); if (p == (POPUP_MENU_PTR)0) { if (window_error_code == NO_HEAP_MEM) /* ... Condition 1,2, or 3 occurred */ else /* Condition 4 occurred */ } Page 186 The C Window Library Page 186 SELECTING FROM POPUP MENUS -------------------------- We have now created the popup menu. Now how do we get the menu manager to act on our popup window? The answer is the PopupSelectMenu() function. PopupSelectMenu() function -------------------------- The PopupSelectMenu() function displays the popup window, and allows the user to move the highlight bar until he/she has placed the bar on the desired option, or the user presses a hotkey to invoke one of the entries. Before the call to the PopupSelectMenu(), nothing has been displayed. This means that you can resize the popup window, change borders, write strings to the popup menus virtual window, etc. while everything is hidden away from view. The only time when the popup menu is displayed is when the call to PopupSelectMenu() is made (or unless you have displayed the popup window yourself using WindowDisplay()). A prototype of the call to PopupSelectMenu() is as follows: int PopupSelectMenu(POPUP_MENU_PTR p, int rank, unsigned start) The first argument is the POPUP_MENU_PTR. The second argument is the rank of the popup window. As with other windows, the rank determines how the window will be situated on the screen with respect to the other windows. The last argument is the number of the menu entry of where the highlight bar should be situated. Usually this is 1, but this will give you the option to start on any one of the menu entries. If the start value is out of bounds (say you have specified start to be 5 while there are only 4 menu entries) the menu manager will default to the first menu option. Now let's put everything together: #include "menu.h" int menu_func(); POPUP_MENU_ENTRY menu_items[] = { " Load F3",1,'L',F3,menu_func, " Pick Alt-F3",2, 'P',ALTF3,menu_func, " New" ,3, 'N',0,menu_func, " Save F2",4, 'S',F2,menu_func, " Write to ",5, 'W',0,menu_func, " Directory ",6, 'D',0,menu_func, " Change Dir" ,7, 'C',0,menu_func, " OS shell" ,8, 'O',0,menu_func, Page 187 The C Window Library Page 187 " Quit Alt-X" ,9,'Q',ALTX,menu_func, CWL_NULL,0}; unsigned int menu_colors[5]; POPUP_MENU_PTR p; main() { WindowInitializeSystem(); WindowSaveInitial(0); /* define colors */ menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,blue); menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(cyan,black); menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); /* create a POPUP_MENU_PTR */ p = PopupCreateMenu(menu_items,menu_colors, 1,1,6, POPUPSTATIC,WNULLFN,VWNULLFN); PopupSelectMenu(p, /* POPUP_MENU_PTR */ 1, /* rank of popup window */ 1 /* menu entry to start on */ ); } int menu_func(POPUP_MENU_PTR p, unsigned which) { WPOINTER w; w = WindowInitialize(BORDER,15,15,40,4, CREATE_VIDEO_ATTRIBUTE(black,white), CREATE_VIDEO_ATTRIBUTE(black,white), SINGLEBOX); WindowOpen(w); WindowClear(w); WindowPrintf(w,"You have selected %s", POPUP_ENTRY_STRING(p,which)); WindowWriteCenterString(w,"Press a key to continue",3); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowFree(w,NOEFFECT); if (which == 9) return POPUP_EXIT; else return POPUP_CONTINUE; } The above example has a call to PopupSelectMenu(). The arguments passed are p as the POPUP_MENU_PTR, a window rank Page 188 The C Window Library Page 188 of 1, and a starting position of 1. The POPUP_ENTRY_STRING() macro in the menu_func() function returns the entry string for the particualr menu entry. The first argument is the POPUP_MENU_PTR and the second argument is the entry number. Values passed to menu function ------------------------------ When a selection is made, the menu manager will call the function defined for the selection, and pass two arguments to this function. The first argument passed is the POPUP_MENU_PTR of the current popup menu and the second argument is the number of the entry selected. Entry numbers are numbered from 1 to the highest entry in the menu. For example, if the " Load F3" entry is selected, the menu manager will pass the POPUP_MENU_PTR p, and a 1 to func(). If " Pick ALT-F3" is chosen, the menu manager passes a 2 as the second argument to func() etc. Values returned to menu manager ------------------------------- The user function must return an integer back to the menu manager. If the value returned to the menu manager is POPUP_EXIT, the menu manager will exit from the current menu and will return control back to the function that called it. If the return value is POPUP_CONTINUE, the menu continues to process selections. The menu_func() function defined above creates a window, displays the entry you have chosen, and returns a value back to the menu manager. If the value is POPUP_EXIT, the menu manager returns control back to the function that called it. In this case, main() called PopupSelectMenu(). A return value of POPUP_CONTINUE will cause the menu manager to let the user make another selection. The menu_func() function is a simple implementation. However your function can do much more sophisticated things, including opening other popup menus. If another popup menu is called while in another popup menu, the new popup menu gets its own menu manager and will not interfere with the original menu manager. This is good if a menu function will call another menu function. Page 189 The C Window Library Page 189 Return Values for PopupSelectMenu() ----------------------------------- If no errors occurred when PopupSelectMenu() is called the menu manager returns NO_ERROR when the menu is closed. There are three possibilities for errors when calling PopupSelectMenu(). Here are the three possible errors: 1) The popup menus window does not exist. 2) The popup menus window is not opened. 3) The virtual window does not exist. The first error occurred because the PopupCreateMenu() function or your custom window function could not initialize the popup menu window, you inadvertently called WindowFree() on the popup menu's window, or you are overwriting data with a stray pointer. Error 2 can occur if the you inadvertently called WindowClose() on the popup menu's window, or you are overwriting data with a stray pointer. Error 3 can occur if PopupCreateMenu() or your custom virtual window function could not create the virtual window, or a stray pointer is overwriting data. For all of the above conditions, you can get the actual error code by checking the value of the global integer window_error_code or by checking the return value of PopupSelectMenu(). Here is a list of return values and their corresponding reasons: Return Value Condition ------------ --------- BAD_WINDOW 1 WINDOW_NOT_OPEN 2 BAD_V_WINDOW 3 Page 190 The C Window Library Page 190 SETTING OPTIONS IN POPUP MENUS ------------------------------ In addition to setting options using the PopupCreateMenu() function, you can turn on and off options at any time using the PopupSetOptions() function. The PopupSetOptions() function ------------------------------ The PopupSetOptions() function turns either one or more of the above options on or off. The prototype to the call is as follows: int PopupSetOptions(POPUP_MENU_PTR p, int option, int switch) The first argument is the POPUP_MENU_PTR. The second argument are the options that you wish to change. The constants that describe the options are exactly the same as the ones described in PopupCreateMenu(). The third argument is whether you want to switch the options on or off. Here are some sample calls to PopupSetOptions(): a) PopupSetOptions(p,POPUPWRAP,1) b) PopupSetOptions(p,POPUPSTATIC,1) c) PopupSetOptions(p,POPUPCONFIRM,1) d) PopupSetOptions(p,POPUPSTATIC,0) e) PopupSetOptions(p,POPUPDISPLAY,1) f) PopupSetOptions(p,POPUPOVERRIDE,1) g) PopupSetOptions(p,POPUPENHANCEDKEY,1) The third argument is 1 for "on", 0 for "off". Example a) sets the highlight bar so that it will wrap. Example b) informs the menu manager that the menu will not be hidden when a selection is made. Example c) will tell the menu manager to call a user defined function that will inform the menu manager whether to invoke the selection in the menu. Example d) Informs the menu manager to hide the menu window when a menu function is invoked. Example e) Informs the menu manager not to hide the menu when control is returned to the function that called PopupSelectMenu(). Example f) Informs the menu manager to process unavailable entries. This is useful if you want to set up your own error routine if the user selects an unavailable entry. Page 191 The C Window Library Page 191 Example g) imforms the menu manager to distinguish between normal keys and enhanced keys. Setting Multiple Options ------------------------ You can also set multiple options with a single call by using a bitwise OR (|). For example: PopupSetOptions(p,POPUPWRAP | POPUPSTATIC | POPUPCONFIRM,1) will set options POPUPWRAP, POPUPSTATIC, and POPUPCONFIRM defined above. Setting the PopupSetConfirmFunction() ------------------------------------- When using the POPUPCONFIRM option, you must also use the PopupSetConfirmFunction() function to point the menu to the confirmation function that will be called when a hotkey is pressed. Here is a prototype of the PopupSetConfirmFunction(): PopupSetConfirmFunction(POPUP_MENU_PTR p, int (*func)()) where p is the desired popup menu to assign the confirmation function to, and func is a pointer to a function that will return a value back to the menu manager that will inform it to either invoke the option, or ignore the option. When the confirmation function is called, the menu manager passes three arguments to func. The prototype for your user defined function should be as follows: int my_confirm_func(POPUP_MENU_PTR p, unsigned key, unsigned sel) where p is the POPUP_MENU_PTR that is currently being processed, key is the hotkey that was pressed, and sel is the selection where the highlight bar is now positioned. The highlight bar is always positioned on the hotkey selection even if it may not be invoked. This user defined function must return a value back to the menu manager. The valid values that can be returned are POPUP_CONTINUE and POPUP_DO_CHOICE. If POPUP_CONTINUE is returned, the menu selection is not invoked, if POPUP_DO_CHOICE is selected, the menu entry is invoked. Here is an example: #include "menu.h" int my_confirm_func(); POPUP_MENU_PTR p; Page 192 The C Window Library Page 192 /* ... */ main() { PopupSetOptions(p,POPUPCONFIRM,1); PopupSetConfirmFunction(p,my_confirm_func); /* ... */ } my_confirm_func(POPUP_MENU_PTR p, unsigned k, unsigned sel) { /* ... */ if (k == 'C' || k == 'c' || k == ALTF) return POPUP_CONTINUE; else return POPUP_DO_CHOICE; } The above function invokes the menu selection if the hotkey that was pressed is not a 'C', 'c', or ALT-F. The confirmation function can do anything, including setting options in the popup menu, displaying other windows etc. Return Values for PopupSetOptions() function -------------------------------------------- You can use the PopupSetOptions() function at any time, including before calling the PopupSelectMenu() function. If the option is not a valid option, the function returns NO_ERROR, but does not change anything. If the switch is not 0 or 1, a 1 is assumed. If there is an error, the error conditions and reasons are the same as the PopupSelectMenu() function defined above. Page 193 The C Window Library Page 193 MAKING MENU ENTRIES AVAILABLE AND UNAVAILABLE --------------------------------------------- There may be cases when a menu entry should be made unavailable. The entry shows up in the menu, but it is a different color than the other entries, and the highlight bar will just skip over this unavailable entry. PopupMakeEntryAvailable() and PopupMakeEntryUnavailable() functions ------------------------------------- With The C Window Library, you can make entries available and unavailable at any time. The PopupMakeEntryAvailable() and the PopupMakeEntryUnavailable() functions perform these tasks. A prototype of the call to both of these functions is as follows: int PopupMakeEntryAvailable(POPUP_MENU_PTR p, unsigned entry) int PopupMakeEntryUnavailable(POPUP_MENU_PTR p, unsigned entry) The first argument is the POPUP_MENU_PTR. The second argument is the number of the entry that you wish to change. Entry numbers range from 1 to the highest entry in the menu. POPUPOVERRIDE option -------------------- If the POPUPOVERRIDE option is set (see above), the menu manager will still process unavailable entries. You must turn off POPUPOVERRIDE by using the PopupSetOptions() function if you do not want to process unavailable entries. Return Values for PopupMakeEntryAvaialble() and PopupMakeEntryUnavailable() functions ----------------------------------------------- If there is no error, both of these functions return NO_ERROR. If there is an error, the following possibilities can occur: 1) The error can be one of the errors defined above for the PopupSelectMenu(). 2) The menu entry is invalid. Page 194 The C Window Library Page 194 Refer to the PopupSelectMenu() return values and reasons for failure defined above for error condition 1). If the error is 2), check to see if the entry number supplied is valid. The entry number cannot be < 1 or greater than the number of selections in the popup menu. If error 2) has occurred, the PopupMakeEntryAvailable() and the PopupMakeEntryUnavailable() return MENU_ENTRY_INVALID. Page 195 The C Window Library Page 195 CHANGING THE MENU ENTRY STRINGS ------------------------------- There may be times when you want to change a POPUP_MENU_ENTRY entry_name string. For instance, you may have a menu entry with the following entry_name: "Default File Name ABC.DAT" If the user selects this choice, the file name should change to another file name the user wants. From there the menu should reflect the new choice the user has made. Let's say the user has changed the default file name to DEF.DAT. The menu then should say: "Default File Name DEF.DAT" PopupChangeEntryString() function --------------------------------- How do you change the entry string? One way is to fool around with the POPUP_MENU_PTR's structure members, and change the string yourself. This is not recommended for the novice to average C programmer, since it is not a good idea to change the structure members directly without a full understanding of the structure. A safer way is to call the PopupChangeEntryString() function. A prototype of this function is as follows: PopupChangeEntryString(POPUP_MENU_PTR p, unsigned entry, char *newstring) The first argument is the POPUP_MENU_PTR. The second argument is the number of the entry that you wish to change. Entry numbers range from 1 to the highest entry in the menu. The third argument is a pointer to the new character string. The newstring cannot be longer than the current POPUP_MENU_ENTRY entry_name string. Return Values for PopupChangeEntryString() function --------------------------------------------------- If there is no error, NO_ERROR is returned. If there is an error, the error conditions and reasons are the same as the PopupMakeEntryAvailable() function defined above. Page 196 The C Window Library Page 196 REDEFINING MENU KEYS -------------------- Setting Global Key Definitions and the popup_key_definition Array ---------------------------------- You can redefine the keys used to control moving the highlight bar, accepting the menu choice, and exiting from the menu. Here is a list of the default key mapping: Function Key Constant -------- --- ------ Move highlight bar up Up Arrow POPUP_UPKEY Move highlight bar down Down Arrow POPUP_DOWNKEY Accept Menu Choice Enter POPUP_ACCEPTKEY Escape Pop-up menu Escape POPUP_QUITKEY Move To First Menu Item Home POPUP_HOMEKEY Move to Last Menu Item End POPUP_ENDKEY Scroll entries up by one page PgUp POPUP_PAGEUPKEY Scroll entries down by one page PgDn POPUP_PAGEDOWNKEY *Move To Next Popup Menu Unassigned POPUP_RIGHTKEY *Move to Previous Popup Menu Unassigned POPUP_LEFTKEY *Escape Pulldown Menu Unassigned POPUP_PULLDOWN_QUITKEY The global array popup_key_definition contains the values of the default popup menu key definitions. The names under the Constant heading are the offsets in the popup_key_definition array of where the key value for the function is defined. For instance, the value for the "Move highlight bar up" function is located at popup_key_definition[POPUP_UPKEY]. You can change the values in popup_key_definition at any time, but make sure that a definition for "Escape Pop-up menu" always exists, and that there are no duplicate definitions (i.e. the "Move highlight bar up" key definition is the same as the "Move highlight bar down" key definition). When defining new key values, you should use the values defined in the keycodes.h header file for non-ascii keys. * The POPUP_RIGHTKEY, POPUP_LEFTKEY, and the POPUP_PULLDOWN_QUITKEY definitions only apply to popup menus that are incorporated in a pulldown menu. See the section on pulldown menus for more information. Setting Local Key Definitions ----------------------------- Another way of redefining menu keys is to load your own array of key definitions with your desired values, and then calling the PopupAssignKeys() function. With this method, each menu can have different key definitions. Page 197 The C Window Library Page 197 PopupAssignKeys() function -------------------------- Here is a prototype of the PopupAssignKeys() function: int PopupAssignKeys(POPUP_MENU_PTR p, unsigned *keys) where p is the POPUP_MENU_PTR, and keys is an array of key definitions. Here is a small code example: #include "menu.h" unsigned mykeys[NUMPOPUPKEYS] = {CTRLU,CTRLD,RETURN, ESC,HOME,END,0,0,0,0}; POPUP_MENU_PTR p; /* Other stuff...*/ main() { /* Assume p is initialized */ /* Assigns my key definitions to popup menu p */ PopupAssignKeys(p,mykeys); } The constant NUMPOPUPKEYS should be used to make sure that your array of key definitions is large enough to hold all the definitions. The above example uses the constants defined in keycodes.h to assign to the array mykeys. Each position in the mykeys array uses the default key mapping explained above. In other words, mykeys[POPUP_UPKEY] is CTRLU, etc. Return Values for PopupAssignKeys() function -------------------------------------------- If there is no error, then NO_ERROR is returned. If there is an error, the error conditions and reasons are the same as the PopupSelectMenu() function defined above. Page 198 The C Window Library Page 198 PROCESSING UNDEFINED KEYS ------------------------- If you are an advanced programmer and/or have experience in using other window/menu libraries, you may be wondering "how do I define a function that supplies context-sensitive help for each POPUP_MENU_ENTRY? There is no structure member in POPUP_MENU_ENTRY that supplies this". With The C Window Library, any key that is not recognized by the menu manager (i.e. the key struck does not invoke a menu option, move the highlight bar up or down, or ends processing of the menu) can be processed by calling a user written function. The WindowGet...() family of functions allowed us to define a function that will be called if a key that has no current definition is pressed. For popup menus, we can do the same thing. The popup_undef_key function pointer ------------------------------------ The global function pointer, popup_undef_key, can point to a user written function that will be called when the menu manager encounters a key that is not defined. The declaration for popup_undef_key is as follows: unsigned int (*popup_undef_key)(POPUP_MENU_PTR p, unsigned int sel, unsigned int *choice) The user written function takes three arguments. The first argument is a pointer to the popup menu that the menu manager is currently processing. The second argument is an integer that contains the value of the key that was pressed. The third argument is a pointer to an integer that will contain the number of the menu choice to execute. Initially, choice points to an integer that contains the current menu choice that the menu highlight bar is situated. For instance, if the highlight bar is on the first menu choice when an undefined key is pressed, *choice will be equal to 1. If popup_undef_key is equal to a Null Function pointer (NULLFN), no user defined function is called. By default, popup_undef_key is assigned to NULLFN. Values returned to menu manager ------------------------------- If popup_undef_key is assigned to a function, the function must return an integer back to the menu manager. This integer value will tell the menu manager how to proceed. Here is a list of the valid return values that the user written function can return: Page 199 The C Window Library Page 199 Return Action to Value Take ------ --------- POPUP_CONTINUE No Action. Continue processing the popup menu. POPUP_MOVE_UP Move the highlight bar up. POPUP_MOVE_DOWN Move the highlight bar down. POPUP_DO_CHOICE Accept and invoke menu entry assigned to *choice. POPUP_MOVE_CONTINUE Move the highlight bar to menu entry assigned to *choice and continue processing menu. POPUP_ESCAPE Escape the popup menu. POPUP_MOVE_HOME Move highlight to first available menu entry. POPUP_MOVE_END Move highlight to last available menu entry. POPUP_MOVE_PAGEUP Scroll the entries in the popup window up by one "page" (a page is the current height of the popup window). POPUP_MOVE_PAGEDOWN Scroll the entries in the popup window down by one "page" (a page is the current height of the popup window). *POPUP_MOVE_LEFT Move to next popup menu. *POPUP_MOVE_RIGHT Move to previous popup menu. *POPUP_PULLDOWN_QUIT Escape pulldown menu A return value of POPUP_CONTINUE is a "do nothing" command to the menu manager. If POPUP_DO_CHOICE is returned to the menu manager, the integer assigned to the parameter *choice is used as the menu entry to invoke. The highlight bar will automatically be moved to the menu choice specified, and the menu function will be called. If POPUP_MOVE_CONTINUE is returned to the menu manager, the highlight bar will be moved to the entry specified by the value of *choice, but no function is called. Return values of POPUP_DO_CHOICE and POPUP_MOVE_CONTINUE only work when the menu entry specified by *choice is an available Page 200 The C Window Library Page 200 entry or the POPUPVERRIDE option is on , otherwise the menu manager just continues processing the popup menu. * The POPUP_MOVE_RIGHT, POPUP_MOVE_LEFT, and POPUP_PULLDOWN_QUIT only apply to popup menus that are incorporated in a pulldown menu system. See the section on pulldown menus for more information. Here is an example of using a user defined function for the undefined keys: #include "menu.h" /* Other includes */ int user_func(); main() { popup_undef_key = user_func; /* Other code */ } unsigned int user_func(POPUP_MENU_PTR p, unsigned sel, unsigned *choice) { switch(sel) { case F1: help(*choice); /* call help function */ return POPUP_CONTINUE; /* return "do nothing" */ case F2: *choice = 6; /* let menu manager know to do choice 6 on the menu */ return POPUP_DO_CHOICE; /* Also let menu manager know we are returning the "do the function assigned to *choice" command */ default: return POPUP_CONTINUE; /* let menu manager know not to do anything */ } } int help(int choice) { /* help function */ switch (choice) { case 1: /* do context-sensitive help for entry 1 */ break; Page 201 The C Window Library Page 201 case 2: /* do context-sensitive help for entry 2 */ break; /* do more entries */ /* ... */ } } In the above example, if the user hits F1, a help function is called. If you wanted to know how to incorporate a help function in the popup menus, here is the way to do it. If the user hits F2, the integer pointed to by choice is assigned a 6, and user_func() returns POPUP_DO_CHOICE to the menu manager. This tells the menu manager to invoke the function assigned to menu entry 6. Page 202 The C Window Library Page 202 PRE-INPUT FUNCTION ------------------ With The C Window Library, you can define a function that will be performed just before the menu manager waits for the user to enter a keystroke. This function can perform just about anything. Setting the global_popup_prefunc function pointer ------------------------------------------------- The global_popup_prefunc function pointer points to this user written function. Here is the prototype: int (*global_popup_prefunc)(POPUP_MENU_PTR p, unsigned *sel) The arguments that will be passed to your function are the following: a) The POPUP_MENU_PTR of the popup menu that called your function, and b) A pointer to the number of the selection that the highlight bar is currently on. The selection number ranges from 1 to the highest entry number of the menu. The pre-input function MUST return a value back to the menu manager. The return values that can be returned are the same as the popup_undef_key function described above. If you are using a version of The C Window Library prior to version 1.5, you must declare your pre-input function as returning an int, and you must return a value back to the menu manager. Versions prior to 1.5 declared the pre-input function as void. The POPUP_DO_CHOICE and POPUP_MOVE_CONTINUE return values will move the highlight bar to the entry number that is assigned to the *sel argument when the pre-input function has returned. By default, global_popup_prefunc points to a NULLFN, and therefore will not be performed. However, you can implement pre-input functions depending on the current selection. For instance, you can write a function that displays extra information for each entry like so: #include "menu.h" char *mess[] = { " This option saves and loads files", " This brings you in edit mode", " This compiles and/or links the current program", Page 203 The C Window Library Page 203 /* ... More stuff */ }; WPOINTER message_window; int disp_info(); main() { /* ... */ global_popup_prefunc = disp_info; /* ... */ } int disp_info(POPUP_MENU_PTR p, unsigned *sel) { /* Assume message_window already created and opened */ WindowClear(message_window, CREATE_VIDEO_ATTRIBUTE(black,white)); WindowWriteString(message_window,mess[*sel-1],1,1); return POPUP_CONTINUE; } For simplicity, the menu definitions are left out of the preceding code sample. The disp_info displays the appropriate description in the window message_window. POPUP_CONTINUE is returned to the menu manager. This informs the menu manager to continue looking for a keystroke. Page 204 The C Window Library Page 204 DISPOSING OF POPUP MENUS ------------------------ PopupMenuFree() --------------- If the popup menu is no longer needed, the PopupMenuFree() function will dispose of the popup menu and return any memory allocated to the popup menu, window, and virtual window memory back to the heap. The call to the function is very simple: PopupMenuFree(POPUP_MENU_PTR p) where p is the POPUP_MENU_PTR to dispose of. Since this function destroys the POPUP_MENU_PTR p, p must not be used for any popup menu functions, unless p is pointing to a valid POPUP_MENU_PTR. Return Values for PopupMenuFree() --------------------------------- The return values and the reasons for failure are the same as PopupSelectMenu(). Page 205 The C Window Library Page 205 BAR MENUS --------- Description ----------- A bar menu is a horizontal menu with a list of entries that are selected by placing a highlight bar on the option and pressing return, or by invoking the function by using a hotkey. Bar menus can span several lines. In other words, menu entries do not have to fit on a single line. Here is a partial list of the various options you can have with bar menus: * Highlight bar wrapping - wrap highlight bar to first or last option when there are no more selections. * Static Menus - menu remains on the screen when entry is selected. * Perpetual Menus - menu remain on the screen regardless of whether the BarSelectMenu() function (explained later) is called or not. * Hidden (Unavailable) entries - You can make an entry in the bar menu unavailable or available at any time. * Color scheme of the menu - You can customize the color of the highlight bar, the hotkey letters, hidden entries, etc. * Change entry names - You can safely change the names displayed in the menu at any time. * Use a mouse to select menu entries. Windows and Virtual Windows --------------------------- Unlike popup menus, bar menus do not use virtual windows. Only normal text windows are used. Page 206 The C Window Library Page 206 CREATING BAR MENUS ------------------ The BAR_MENU_ENTRY structure ---------------------------- The two most important parts of the bar menu are the BAR_MENU_ENTRY structure and the BAR_MENU_PTR structure. The BAR_MENU_ENTRY structure is the first step in creating a bar menu and is discussed here. Each entry in the bar menu has its own BAR_MENU_ENTRY structure associated with it. The layout of this structure is as follows: char *entry_name -- This is the string that is displayed in the bar window. unsigned row -- Row in the window to display entry_name. char hotkey_letter -- This is a character in entry_name that is highlighted from the rest of the characters in entry_name. This letter will automatically invoke the menu function associated with entry_name. unsigned ext_hotkey -- This is a secondary hotkey. The difference between hotkey_letter and ext_hotkey is that ext_hotkey can handle keys that are not ASCII keys (the F keys, Alt and Ctrl key combinations, etc.). int (*func)() -- Pointer to function that is invoked when option is selected. An array of BAR_MENU_ENTRY's are needed to create all of the entries on the bar menu. The order of the array elements determine the order of how they are placed in the window. A code sample to create an array of BAR_MENU_ENTRY's would be as follows: #include "menu.h" int menu_func(); BAR_MENU_ENTRY bar_items[] = { "File", /* option name */ 1, /* row in window to display option name */ 4, /* col. in window to display option */ Page 207 The C Window Library Page 207 'F', /* hotkey letter */ ALTF, /* secondary hotkey */ rt2, /* function to do if chosen */ , /* Now define the rest of the BAR_MENU_ENTRY's */ "Edit",1,10,'E',0,menu_func, "Run",1,17,'R',0,menu_func, "Compile",1,23,'C',0,menu_func, "Project",1,33,'P',0,menu_func, "Options",1,43,'O',0,menu_func, "Debug",1,53,'D',0,menu_func, "Break/watch",1,61,'B',0,menu_func, /* Now terminate with a CWL_NULL option_name */ CWL_NULL}; The first include file, menu.h, is must be included in each source file that calls menu functions. As you can see, there is an array of BAR_MENU_ENTRY's, namely bar_items. Each entry consists of an entry name, row number, column number, hotkey letter, secondary hotkey, and a function to call when the entry is selected. The list of BAR_MENU_ENTRY's MUST be terminated by a CWL_NULL entry name. There is an alternate method of creating the BAR_MENU_ENTRY array. Later on, we will discuss creating these entries dynamically. Defining Hotkeys ---------------- The hotkey_letter defined in the BAR_MENU_ENTRY structure must match one of the letters in its corresponding entry_name. For example, "File", has the hotkey_letter defined as 'F'. Since 'F' matches the first letter in "File", the first 'F' in "File" is highlighted. If there is no match, or if the hotkey_letter is 0, there is no hotkey associated with this entry. When the menu is displayed, either the 'f' or 'F' will be accepted as a valid selection to the entry "File". If there is a BAR_MENU_ENTRY with the same hotkey letter as another BAR_MENU_ENTRY, the BAR_MENU_ENTRY closest to the first entry is chosen. Page 208 The C Window Library Page 208 The ext_hotkey is used if the hotkey cannot be defined as a single character, or if you want another hotkey definition. In the above example, the "File" entry_name has an ext_hotkey of ALTF3 (defined in keycodes.h). If the ALT-F3 key is pressed, the function rt2() is automatically invoked. If the ext_hotkey letter is 0, there is no ext_hotkey defined. If there is a BAR_MENU_ENTRY with the same ext_hotkey as another BAR_MENU_ENTRY, the BAR_MENU_ENTRY closest to the first entry is chosen. Assigning the function to perform --------------------------------- The func() member is the function that is performed when its corresponding entry_name is chosen. This is the first step in completing the total bar menu. Once the array of BAR_MENU_ENTRY's is created the next step is to define the colors for each element of the bar menu. Coloring Bar Menus ------------------ An array of unsigned integers is used to define the color scheme of the bar menu. Each element of this array stands for a certain area of the bar menu. Here is a list of array positions and what they stand for. Position Constant -------- ENTRYCOLOR -- color of the text area of the window. BORDERCOLOR -- color of the border of the window. HOTKEYCOLOR -- color of the hotkey letter. HIGHLIGHTCOLOR -- color of the highlight bar. UNAVAILCOLOR -- color of the unavailable entries. Position ENTRYCOLOR of the array defines the color of the text area of the viewport window. This in turn defines the color of each entry_name of all of the BAR_MENU_ENTRY's. Position BORDERCOLOR defines the color of the border of the window. If the window does not have a border, this attribute is ignored. Page 209 The C Window Library Page 209 Position HOTKEYCOLOR defines the color to use for the hotkey letter. In the above example, the 'L', 'P', 'N', etc. of each respective entry_name is displayed using this color. Position HIGHLIGHTCOLOR defines the color used for the highlight bar. This bar is moved up and down when the user is making a selection. Position UNAVAILCOLOR defines the color of the unavailable menu entries. Whenever a menu entry is unavailable, the entry_name string displayed takes on this color. Colors can be created by using the CREATE_VIDEO_ATTRIBUTE() macro. A code sample to create the colors is as follows: #include "menu.h" unsigned int menu_colors[5]; main() { {... code ...} menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white); menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white); menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(blue,white); menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,cyan); menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); /* rest of the program */ } Creating bar menu entries dynamically ------------------------------------- You can create BAR_MENU_ENTRY's dynamically, instead of defining a pre-determined array of BAR_MENU_ENTRY's explained previously. Here is an example: Usual method: ------------ #include "menu.h" int menu_func(); BAR_MENU_ENTRY bar_items[] = { "File",1,4,'F',ALTF,menu_func, "Edit",1,10,'E',0,menu_func, "Run",1,17,'R',0,menu_func, Page 210 The C Window Library Page 210 "Compile",1,23,'C',0,menu_func, "Project",1,33,'P',0,menu_func, "Options", 1,43,'O',0,menu_func, "Debug",1,53,'D',0,menu_func, "Break/watch",1,61,'B',0,menu_func, CWL_NULL}; Dymamic Method -------------- #include "menu.h" #define NUMENTRIES 8 BAR_MENU_ENTRY_PTR menu_array; /* Notice that we have a pointer to what will be an array of BAR_MENU_ENTRY's */ BAR_MENU_PTR b; main() { WindowInitializeSystem(); /* Initialize with at least number of total entries */ menu_array = BarAllocate(NUMENTRIES); /* Call function to create entries in menu_array sequentially */ BarCreateEntry(menu_array,/* BAR_MENU_ENTRY pointer */ 1, /* entry number */ /* The rest of the arguments are just like the old method */ "File", /* menu string */ 1, /* row number */ 4, /* col. number */ 'F', /* hotkey letter */ ALTF, /* secondary hotkey */ menu_func); /* function to perform */ /* do rest of the entries */ BarCreateEntry(menu_array,2,"Edit",1,10,'E',0,menu_func); BarCreateEntry(menu_array,3,"Run",1,17,'R',0,menu_func); BarCreateEntry(menu_array,4,"Compfile",1,23,'C',0, menu_func); BarCreateEntry(menu_array,5,"Project",1,33,'P',0,menu_func); BarCreateEntry(menu_array,6,"Options",1,43,'O',0,menu_func); BarCreateEntry(menu_array,7,"Debug", 1,53,'D',0,menu_func); BarCreateEntry(menu_array,8,"Break/watch",1,61,'B',0, menu_func); /* end all of the menu entries */ BarEntryEnd(menu_array,NUMENTRIES); Page 211 The C Window Library Page 211 /* create menu */ b = BarCreateMenu(menu_array, /* rest of the arguments */); /* ... */ /* Dispose of menu entries created */ BarDeallocate(menu_array); } The difference between the above method and the method used to globally initialize an array of BAR_MENU_ENTRY's are the following: 1) The variable type for menu_array is BAR_MENU_ENTRY_PTR, not BAR_MENU_ENTRY as the normal method would have done. 2) You must call the BarAllocate() function to allocate space for the number of entries desired. If you do not call BarAllocate(), you will surely get a memory overwrite error. The return value to BarAllocate() must be assigned to a BAR_MENU_ENTRY_PTR, as the above example shows. The array of menu entries are allocated from the heap at runtime, as opposed to the static method which sets up the memory scheme at link time. 3) The next thing you must do is to fill in the entry information by calling the BarCreateEntry() function. The first argument to the BarCreateEntry() function is the BAR_MENU_ENTRY_PTR. The second argument is the entry number to assign this information to. The rest of the arguments are the same order as the usual method i.e. menu string, row, column, hotkey, etc. BarCreateEntry() is called for each field desired. 4) The BarEndEntry() function must be called to terminate the list of entries. The first argument is the BAR_MENU_ENTRY_PTR, and the second argument is the total number of entries defined. 5) You should call BarDeallocate() to free the memory assigned to the array of menu_entries. The only argument to BarDeallocate() is the BAR_MENU_ENTRY_PTR. Only call BarDeallocate() after you have called BarMenuFree() or any function that disposes of the BAR_MENU_PTR. All of these functions except for BarAllocate() have no return values. The BarAllocate() function returns a BAR_MENU_ENTRY_PTR if successful, and a null pointer if unsuccessful. Page 212 The C Window Library Page 212 You could also do the following: #include "menu.h" #define NUMENTRIES 8 BAR_MENU_ENTRY menu_array[NUMENTRIES+1]; /* We must have at least 1 more than the number of entries */ BAR_MENU_PTR b; main() { /* ... */ /* Call function to create entries in menu_array sequentially */ BarCreateEntry(menu_array, /* BAR_MENU_ENTRY pointer */ 1, /* entry number */ /* The rest of the arguments are just like the old method */ "File", /* menu string */ 1, /* row number */ 4, /* col. number */ 'F', /* hotkey letter */ ALTF, /* secondary hotkey */ menu_func); /* function to perform */ /* do rest of the entries */ BarCreateEntry(menu_array,2,"Edit",1,10,'E',0,menu_func); BarCreateEntry(menu_array,3,"Run",1,17,'R',0,menu_func); BarCreateEntry(menu_array,4,"Compfile",1,23,'C',0, menu_func); BarCreateEntry(menu_array,5,"Project",1,33,'P',0,menu_func); BarCreateEntry(menu_array,6,"Options",1,43,'O',0,menu_func); BarCreateEntry(menu_array,7,"Debug", 1,53,'D',0,menu_func); BarCreateEntry(menu_array,8,"Break/watch",1,61,'B',0, menu_func); /* end all of the menu entries */ BarEntryEnd(menu_array,NUMENTRIES); } The method above does not call BarAllocate() because the number of entries was already determined and an array was already set up at compile time. BarCreateEntry() is called for each menu entry as before, and BarEntryEnd() is called to terminate the menu entries. To use this method, you must declare an array of menu entries with at least one more than the desired number of entries. Also note that BarDeallocate() MUST NOT be called because the array of menu entries was not created with BarAllocate(). Page 213 The C Window Library Page 213 BarCreateMenu() function ------------------------ Now that you have created the BAR_MENU_ENTRY's, and defined the color scheme, it is time to wrap all of these loose ends in one package. The next step is to call the BarCreateMenu() function. This function combines all of the BAR_MENU_ENTRY's, the colors you have defined, and other information into one entity called a BAR_MENU_PTR. A BAR_MENU_PTR is a bar menu structure. Just like a WPOINTER is a pointer to a window, a BAR_MENU_PTR is used to reference the bar menu. A prototype of the call to BarCreateMenu() is as follows: BAR_MENU_PTR BarCreateMenu(BAR_MENU_ENTRY *b, unsigned *c, int row, int col, unsigned options, WPOINTER (*wfunc)()) To illustrate how to use this call, let's use the BAR_MENU_ENTRY's and colors created in the previous examples: #include "menu.h" int menu_func(); BAR_MENU_ENTRY bar_items[] = { "File",1,4,'F',ALTF,NULLFN, "Edit",1,10,'E',0,edit, "Run",1,17,'R',0,NULLFN, "Compile",1,23,'C',0,NULLFN, "Project",1,33,'P',0,NULLFN, "Options", 1,43,'O',0,NULLFN, "Debug",1,53,'D',0,NULLFN, "Break/watch",1,61,'B',0,NULLFN, CWL_NULL}; unsigned int menu_colors[5]; BAR_MENU_PTR b; main() { WindowInitializeSystem(); /* Initialize C Window Library */ /* define colors */ menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white); menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,white); Page 214 The C Window Library Page 214 menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(blue,white); menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(black,cyan); menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); /* create a BAR_MENU_PTR */ WindowSaveInitial(0); /* Save initial screen */ b = BarCreateMenu(menu_items,menu_colors,1,1, NO_BAR_OPTIONS,WNULLFN); /* rest of the code */ } In the example above there are two function calls that must be done before calling BarCreateMenu(). The first mandatory function is WindowInitializeSystem(). The other function must be WindowSaveInitial() The WindowInitializeSystem() function must be called to initialize global variables used by the menu manager. The WindowSaveInitial() function is a mandatory function because the BarCreateMenu() function creates windows and assumes that the base screen has been saved. The example above declares the variable b to be a BAR_MENU_PTR. This BAR_MENU_PTR is going to be used to reference the bar menu throughout the program. The first argument is a pointer to the first BAR_MENU_ENTRY. In the above example, menu_items is a pointer to the first BAR_MENU_ENTRY. The second argument is a pointer to the array of colors. In our example, menu_colors is our array of colors. The third and fourth arguments denote the row and column to place the upper left hand corner of the bar menu window. The fifth argument are various bar menu options that are assigned to the bar menus which are defined below. Bar Menu Options ---------------- By default the menu manager assumes the following things: 1) The highlight bar does not wrap if the user wants to move the bar past the last entry, or before the first entry. Page 215 The C Window Library Page 215 2) The menu will be hidden from the screen when a selection is made and will reappear when control is returned to the menu manager. 3) A function is automatically invoked when the hotkey is pressed instead of calling a user-defined function which will tell the menu manager whether the menu entry is to be executed. 4) The bar menu window is hidden when the menu manager returns control to the calling function. 5) The highlight bar will skip unavailable entries. 6) The menu manager does not recognize enhanced keys (F11, F12, etc.). 7) The mouse will not be used to move the highlight bar. 8) Scroll characters will not be displayed on the bar window. The scroll characters allow the user to scroll through the options with a mouse. The last two options are only available if you have a Microsoft compatible mouse, and the mouse is activated. If the constant NO_BAR_OPTIONS is used, the assumptions above are used. If you want to override the above defaults, use the following options: Option Name Definition ----------- ---------- BARWRAP Highlight bar wrapping. BARSTATIC Do not hide menu when selection is made. BARCONFIRM Confirmation when selection is made via hotkey. BARDISPLAY Display menu even after exit. BAROVERRIDE Accept Unavailable entries. BARENHANCEDKEY Recognize enhanced keys. BARMOUSE Use the mouse to select entries. As was stated before, the last option, BARMOUSE can only be used if you have a mouse installed, and the mouse is activated. More information on these two options is given in the USING THE MOUSE section. Page 216 The C Window Library Page 216 By turning the above options "on" the following is assumed: 1) BARWRAP will wrap the highlight bar if the user wants to move the bar past the last entry or before the first entry. 2) BARSTATIC will not hide the menu when a selection is made. 3) BARCONFIRM will call a user-defined function before invoking the hotkey that was selected. This function will then return an integer back to the menu manager informing whether the function selected should be invoked, or the request should be rejected. There is more information on this option in the SETTING OPTIONS IN BAR MENUS section below. 4) BARDISPLAY will not hide the bar window when the menu manager returns control to the calling function. 5) BAROVERRIDE will make the menu manager accept unavailable entries. 6) BARENHANCEDKEY will inform the menu manager that enhanced keys will be recognized. 7) BARMOUSE allows the use of a mouse to make selections. You can also set multiple options by using a bitwise OR (|). For example: b = BarCreateMenu(arg1,arg2,arg3,arg4, BARWRAP | BARSTATIC | BARCONFIRM,arg5) will set options BARWRAP, BARSTATIC, and BARCONFIRM defined above. The last argument to BarCreateMenu() is defined in the next sections. Default Bar Menu Window and Creating Your own Windows ----------------------------------------------------- The sixth argument to the BarCreateMenu() function is a pointer to a function that will open a bar menu window. If this is a NULL function pointer (WNULLFN), the menu manager will create a window. For most applications, the window that the menu manager will create is adequate. The menu manager uses these defaults when making the bar window: - A bordered window with the border consisting of single lines (SINGLEBOX). Page 217 The C Window Library Page 217 - The width of the window is determined by the longest row of entry names. If you want to create your own bar menu window, your function must return a WPOINTER. Inside your function you must create and open a window using WindowInitialize() and WindowOpen(). For most applications, you do not have to display the window, instead the menu manager can do the displaying and hiding of the windows. Here is an example of creating your own custom window function: #include "menu.h" /* Other includes and menu stuff */ WPOINTER my_open(); BAR_MENU_PTR b; main() { /* Other code */ b = BarCreateMenu(menu_items,menu_colors,1,1, NO_BAR_OPTIONS,my_open); /* More code */ } WPOINTER my_open() { WPOINTER w; w = WindowInitialize(NOBORDER,1,1,80,1,BLACKONWHITE, BLACKONWHITE,""); WindowOpen(w); return w; /* May be null pointer, but must return to BarCreateMenu() */ } The example above lets the menu manager know that the window creation function is a user written function called my_open. The row, column and height arguments (arguments 3 and 4) of BarCreateMenu() will be ignored when using a custom window function. The row and column height parameters used to create the window in the call to WindowInitialize() in my_window() will take precedence over the arguments 3 and 4 used in BarCreateMenu(). It is the programmer's responsibility to make sure that the window that is created is wide and tall enough to hold all of the menu entries. If not, the results will be unpredictable. Page 218 The C Window Library Page 218 Accessing bar menu windows -------------------------- After calling the BarCreateMenu() function, you can access the bar window by using the BAR_WINDOW() macro. In the above example, b is the BAR_MENU_PTR and the value of BAR_WINDOW(b) is a pointer to the bar menu's window. If you want to change borders move, slide, or anything you can do with normal windows, you must access the bar window in this way. For example, if you want to change the border of the bar window you would do the following: b = BarCreateMenu(... /* other arguments */ ) /* change border to a double lined box */ WindowDrawBorder(BAR_WINDOW(b),DOUBLEBOX); The example calls WindowDrawBorder() to change the border of the bar window. Warnings -------- Do not call WindowFree(), WindowClose() on the window of the bar menu. The menu manager will call these functions when BarMenuFree() is called. If you close the bar window on an active menu, the menu manager will assume that the bar window still exists. Doing so will almost guarantee your application will bomb out. Return Values for BarCreateMenu() --------------------------------- If there are no errors, BarCreateMenu() returns a valid BAR_MENU_PTR pointer. If there is an error when BarCreateMenu() is called, a null BAR_MENU_PTR is returned. Here are the possible reasons why an error has occurred: 1) There is not enough memory to allocate for the BAR_MENU_PTR or its internal data structures. 2) There is not enough memory to allocate for the bar window. 3) The bar window's size was invalid. Problems 1 and 2 all are caused by a lack of heap memory. Problem 3 stems from having invalid parameters in the BarCreateMenu(). The arguments that are suspect are the third and fourth. To remedy this problem, adjust these arguments such that the window can fit on the screen. Page 219 The C Window Library Page 219 For all of the above conditions, you can get the actual error code by checking the value of the global integer window_error_code. If window_error_code is equal to NO_HEAP_MEM, then condition 1 or 2 has occurred. If it is equal to BAD_WINDOW_SIZE, then condition 3 has occurred. If you have a custom window opening function, it is your responsibility to check the error conditions that may occur, and return a correct value or a null pointer if you cannot rectify the error in your custom routine. Here is an example: int status; BAR_MENU_PTR b; b = BarCreateMenu(...); if (b == (BAR_MENU_PTR)0) { if (window_error_code == NO_HEAP_MEM) /* ... Condition 1 or 2 occurred */ else /* Condition 3 occurred */ } Page 220 The C Window Library Page 220 SELECTING FROM BAR MENUS ------------------------ We have now created the bar menu. Now how do we get the menu manager to act on our bar window? The answer is the BarSelectMenu() function. BarSelectMenu() function ------------------------ The BarSelectMenu() function displays the bar window, and allows the user to move the highlight bar until he/she has placed the bar on the desired entry, or the user presses a hotkey to invoke one of the entries. Before the call to the BarSelectMenu(), nothing has been displayed. This means that you can resize the bar window, change borders etc. while everything is hidden away from view. The only time when the bar menu is displayed is when the call to BarSelectMenu() is made (or unless you have displayed the bar window yourself using WindowDisplay()). A prototype of the call to BarSelectMenu() is as follows: int BarSelectMenu(BAR_MENU_PTR b, int rank, unsigned start) The first argument is the BAR_MENU_PTR. The second argument is the rank of the bar window. As with other windows, the rank determines how the window will be situated on the screen with respect to the other windows. The last argument is the number of the menu entry of where the highlight bar should be situated. Usually this is 1, but this will give you the option to start on any one of the menu entries. If the start value is out of bounds (say you have specified start to be 5 while there are only 4 menu entries) the menu manager will default to the first menu entry. Now let's put everything together: #include "menu.h" int menu_func(); BAR_MENU_ENTRY bar_items[] = { "File",1,4,'F',ALTF,menu_func, "Edit",1,10,'E',0,menu_func, "Run",1,17,'R',0,menu_func, "Compile",1,23,'C',0,menu_func, "Project",1,33,'P',0,menu_func, "Options", 1,43,'O',0,menu_func, "Debug",1,53,'D',0,menu_func, "Break/watch",1,61,'B',0,menu_func, CWL_NULL}; Page 221 The C Window Library Page 221 unsigned int menu_colors[5]; BAR_MENU_PTR b; main() { WindowInitializeSystem(); WindowSaveInitial(0); menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,blue); menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(cyan,black); menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); /* create a BAR_MENU_PTR */ b = BarCreateMenu(bar_items,menu_colors, 1,1, BARSTATIC | BARWRAP,WNULLFN); BarSelectMenu(b,1,1); } int menu_func(BAR_MENU_PTR b, unsigned which) { WPOINTER w; w = WindowInitialize(BORDER,15,15,40,4, CREATE_VIDEO_ATTRIBUTE(black,white), CREATE_VIDEO_ATTRIBUTE(black,white), SINGLEBOX); WindowOpen(w); WindowPrintf(w,"You have selected %s", BAR_ENTRY_STRING(b,which)); WindowWriteCenterString(w,"Press a key to continue",3); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowFree(w,NOEFFECT); if (which == 9) return BAR_EXIT; else return BAR_CONTINUE; } The above example has a call to BarSelectMenu(). The arguments passed are b as the BAR_MENU_PTR, a window rank of 1, and a starting position of 1. The BAR_ENTRY_STRING() macro that is called in menu_func() returns the entry string of a desired entry in a BAR_MENU_PTR. The first argument is the BAR_MENU_PTR, and the second argument is the entry number of the entry desired. Page 222 The C Window Library Page 222 Values passed to menu function ------------------------------ When a selection is made, the menu manager will call the function defined for the selection, and pass two arguments to this function. The first argument passed is the BAR_MENU_PTR of the current bar menu and the second argument is the number of the item selected. Item numbers are numbered from 1 to the highest entry in the menu. For example, if the "File" entry is selected, the menu manager will pass the BAR_MENU_PTR b, and a 1 to func(). If "Edit" is chosen, the menu manager passes a 2 as the second argument to func() etc. Values returned to menu manager ------------------------------- The user function must return an integer back to the menu manager. If the value returned to the menu manager is BAR_EXIT, the menu manager will exit from the current menu and will return control back to the function that called it. If the return value is BAR_CONTINUE, the menu continues to process selections. The menu_func() function defined above creates a window, displays the entry you have chosen, and returns a value back to the menu manager. If the value is BAR_EXIT, the menu manager returns control back to the function that called it. In this case, main() called BarSelectMenu(). A return value of BAR_CONTINUE will cause the menu manager to let the user make another selection. The menu_func() function is a simple implementation. However your function can do much more sophisticated things, including opening other bar menus. If another bar menu is called while in another bar menu, the new bar menu gets its own menu manager and will not interfere with the original menu manager. This is good if a menu function will call another menu function. Return Values for BarSelectMenu() --------------------------------- If no errors occurred when BarSelectMenu() is called the menu manager returns NO_ERROR when the menu is closed. There are three possibilities for errors when calling BarSelectMenu(). Here are the three possible errors: 1) The bar menu's window does not exist. 2) The bar menu's window is not opened. The first error occurred because the BarCreateMenu() function Page 223 The C Window Library Page 223 or your custom window function could not initialize the bar menu window, you inadvertently called WindowFree() on the bar menu's window, or you are overwriting data with a stray pointer. Error 2 can occur if the you inadvertently called WindowClose() on the bar menu's window, or you are overwriting data with a stray pointer. For all of the above conditions, you can get the actual error code by checking the value of the global integer window_error_code or by checking the return value of BarSelectMenu(). Here is a list of return values and their corresponding reasons: Return Value Condition ------------ --------- BAD_WINDOW 1 WINDOW_NOT_OPEN 2 Page 224 The C Window Library Page 224 SETTING OPTIONS IN BAR MENUS ---------------------------- In addition to setting options using the BarCreateMenu() function, you can turn on and off options at any time using the BarSetOptions() function. The BarSetOptions() function ---------------------------- The BarSetOptions() function turns either one or more of the above options on or off. The prototype to the call is as follows: int BarSetOptions(BAR_MENU_PTR b, int option, int switch) The first argument is the BAR_MENU_PTR. The second argument are the options that you wish to change. The constants that describe the options are exactly the same as the ones described in BarCreateMenu(). The third argument is whether you want to switch the options on or off. Here are some sample calls to BarSetOptions(): a) BarSetOptions(b,BARWRAP,1) b) BarSetOptions(b,BARSTATIC,1) c) BarSetOptions(b,BARCONFIRM,1) d) BarSetOptions(b,BARSTATIC,0) e) BarSetOptions(b,BARDISPLAY,1) f) BarSetOptions(b,BAROVERRIDE,1) g) BarSetOptions(b,BARENHANCEDKEY,1) The third argument is 1 for "on", 0 for "off". Example a) sets the highlight bar so that it will wrap. Example b) informs the menu manager that the menu will not be hidden when a selection is made. Example c) will tell the menu manager to call a user defined function that will inform the menu manager whether to invoke the selection in the menu. Example d) Informs the menu manager to hide the menu window when a menu function is invoked. Example e) Informs the menu manager not to hide the menu when control is returned to the function that called BarSelectMenu(). Example f) Informs the menu manager to process unavailable entries. This is useful if you want to set up your own error routine if the user selects an unavailable entry. Page 225 The C Window Library Page 225 Example g) imforms the menu manager to distinguish between normal keys and enhanced keys. Setting Multiple Options ------------------------ You can also set multiple options with a single call by using a bitwise OR (|). For example: BarSetOptions(b,BARWRAP | BARSTATIC | BARCONFIRM,1) will set options BARWRAP, BARSTATIC, and BARCONFIRM defined above. Setting the BarSetConfirmFunction() ----------------------------------- When using the BARCONFIRM option, you must also use the BarSetConfirmFunction() function to point the menu to the confirmation function that will be called when a hotkey is pressed. Here is a prototype of the BarSetConfirmFunction(): int BarSetConfirmFunction(BAR_MENU_PTR b, int (*func)()) where b is the desired bar menu to assign the confirmation function to, and func is a pointer to a function that will return a value back to the menu manager that will inform it to either invoke the option, or ignore the option. When the confirmation function is called, the menu manager passes three arguments to func. The prototype for your user defined function should be as follows: int my_confirm_func(BAR_MENU_PTR b, unsigned key, unsigned sel) where b is the BAR_MENU_PTR that is currently being processed, key is the hotkey that was pressed, and sel is the selection where the highlight bar is now positioned. The highlight bar is always positioned on the hotkey selection even if it may not be invoked. This user defined function must return a value back to the menu manager. The valid values that can be returned are BAR_CONTINUE and BAR_DO_CHOICE. If BAR_CONTINUE is returned, the menu selection is not invoked, if BAR_DO_CHOICE is selected, the menu entry is invoked. Here is an example: #include "menu.h" int my_confirm_func(); BAR_MENU_PTR b; Page 226 The C Window Library Page 226 /* ... */ main() { BarSetOptions(b,BARCONFIRM,1); BarSetConfirmFunction(b,my_confirm_func); /* ... */ } my_confirm_func(BAR_MENU_PTR b, unsigned k, unsigned sel) { /* ... */ if (k == 'C' || k == 'c' || k == ALTF) return BAR_CONTINUE; else return BAR_DO_CHOICE; } The above function invokes the menu selection if the hotkey that was pressed is not a 'C', 'c', or ALT-F. The confirmation function can do anything, including setting options in the bar menu, displaying other windows etc. Return Values for BarSetOptions() function ------------------------------------------ You can use the BarSetOptions() function at any time, including before calling the BarSelectMenu() function. If the option is not a valid option, the function returns NO_ERROR, but does not change anything. If the switch is not 0 or 1, a 1 is assumed. If there is an error, the error conditions and reasons are the same as the BarSelectMenu() function defined above. Page 227 The C Window Library Page 227 MAKING ENTRIES AVAILABLE AND UNAVAILABLE ---------------------------------------- There may be cases when a menu entry should be made unavailable. The entry shows up in the menu, but it is a different color than the other entries, and the highlight bar will just skip over this unavailable entry. BarMakeEntryAvailable() and BarMakeEntryUnavailable() functions ----------------------------------- With The C Window Library, you can make entries available and unavailable at any time. The BarMakeEntryAvailable() and the BarMakeEntryUnavailable() functions perform these tasks. A prototype of the call to both of these functions is as follows: int BarMakeEntryAvailable(BAR_MENU_PTR b, unsigned entry) int BarMakeEntryUnavailable(BAR_MENU_PTR b, unsigned entry) The first argument is the BAR_MENU_PTR. The second argument is the number of the entry that you wish to change. Entry numbers range from 1 to the highest entry in the menu. BAROVERRIDE option ------------------ If the BAROVERRIDE option is set (see above), the menu manager will still process unavailable entries. You must turn off BAROVERRIDE by using the BarSetOptions() function if you do not want to process unavailable entries. Return Values for BarMakeEntryAvaialble() and BarMakeEntryUnavailable() functions --------------------------------------------- If there is no error, both of these functions return NO_ERROR. If there is an error, the following possibilities can occur: 1) The error can be one of the errors defined above for the BarSelectMenu(). 2) The menu entry is invalid. Refer to the BarSelectMenu() return values and reasons for failure defined above for error condition 1). If the error is 2), check to see if the entry number supplied is valid. The entry number cannot be < 1 or greater than the number of Page 228 The C Window Library Page 228 selections in the bar menu. If error 2) has occurred, the BarMakeEntryAvailable() and the BarMakeEntryUnavailable() return MENU_ENTRY_INVALID. Page 229 The C Window Library Page 229 CHANGING THE MENU OPTIONS STRING -------------------------------- There may be times when you want to change a BAR_MENU_ENTRY entry_name string. For instance, you may have a menu entry with the following entry_name: "Default File Name ABC.DAT" If the user selects this choice, the file name should change to another file name the user wants. From there the menu should reflect the new choice the user has made. Let's say the user has changed the default file name to DEF.DAT. The menu then should say: "Default File Name DEF.DAT" BarChangeEntryString() function ------------------------------- How do you change the entry string? One way is to fool around with the BAR_MENU_PTR's structure members, and change the string yourself. This is not recommended for the novice to average C programmer, since it is not a good idea to change the structure members directly without a full understanding of the structure. A safer way is to call the BarChangeEntryString() function. A prototype of this function is as follows: int BarChangeEntryString(BAR_MENU_PTR b, unsigned entry, char *newstring) The first argument is the BAR_MENU_PTR. The second argument is the number of the entry that you wish to change. Entry numbers range from 1 to the highest entry in the menu. The third argument is a pointer to the new character string. Remember that the width of the bar menu's window is equal to the width of the longest line of entry_name entries, therefore newstring cannot exceed the boundaries of the bar menu window (unless you will called WindowResizeWidth() or WindowResizeHeight() to resize the window). Return Values for BarChangeEntryString() function ------------------------------------------------- If there is no error, then NO_ERROR is returned. Page 230 The C Window Library Page 230 If there is an error, the error conditions and reasons are the same as the BarMakeEntryAvailable() function defined above. Page 231 The C Window Library Page 231 REDEFINING THE MENU KEYS ------------------------ Setting Global Key Definitions and the bar_key_definition Array ---------------------------------- You can redefine the keys used to control moving the highlight bar, accepting the menu choice, and exiting from the menu. Here is a list of the default key mapping: Function Key Constant -------- --- ------ Move highlight bar right Up Arrow BAR_RIGHTKEY Move highlight bar left Down Arrow BAR_LEFTKEY Accept Menu Choice Enter BAR_ACCEPTKEY Escape Bar menu Escape BAR_QUITKEY Move To First Menu Item Home BAR_HOMEKEY Move to Last Menu Item End BAR_ENDKEY The global array bar_key_definition contains the values of the default bar menu key definitions. The names under the Constant heading are the offsets in the bar_key_definition array of where the key value for the function is defined. For instance, the value for the "Move highlight bar up" function is located at bar_key_definition[BAR_RIGHTKEY]. You can change the values in bar_key_definition at any time, but make sure that a definition for "Escape Bar menu" always exists, and that there are no duplicate definitions (i.e. the "Move highlight bar up" key definition is the same as the "Move highlight bar down" key definition). When defining new key values, you should use the values defined in the keycodes.h header file for non-ascii keys. Setting Local Key Definitions ----------------------------- Another way of redefining menu keys is to load your own array of key definitions with your desired values, and then calling the BarAssignKeys() function. With this method, each menu can have different key definitions. BarAssignKeys() function ------------------------ Here is a prototype of the BarAssignKeys() function: int BarAssignKeys(BAR_MENU_PTR b, unsigned *keys) where b is the BAR_MENU_PTR, and keys is an array of key Page 232 The C Window Library Page 232 definitions. Here is a small code example: #include "menu.h" unsigned mykeys[8] = {CTRLR,CTRLL,RETURN,ESC,HOME,END}; BAR_MENU_PTR b; /* Other stuff...*/ main() { /* Assume b is initialized */ BarAssignKeys(b,mykeys); /* Assigns my key definitions to bar menu b */ } The above example uses the constants defined in keycodes.h to assign to the array mykeys. Each position in the mykeys array uses the default key mapping explained above. In other words, mykeys[BAR_RIGHTKEY] is CTRLR, etc. Return Values for BarAssignKeys() function ------------------------------------------ If there is no error, then NO_ERROR is returned. If there is an error, the error conditions and reasons are the same as the BarSelectMenu() function defined above. Page 233 The C Window Library Page 233 PROCESSING UNDEFINED KEYS ------------------------- If you are an advanced programmer and/or have experience in using other window/menu libraries, you may be wondering "how do I define a function that supplies context-sensitive help for each BAR_MENU_ENTRY? There is no structure member in BAR_MENU_ENTRY that supplies this". With The C Window Library, any key that is not recognized by the menu manager (i.e. the key struck does not invoke a menu option, move the highlight bar up or down, or ends processing of the menu) can be processed by calling a user written function. The WindowGet...() family of functions allowed us to define a function that will be called if a key that has no current definition is pressed. For bar menus, we can do the same thing. The bar_undef_key function pointer ---------------------------------- The global function pointer, bar_undef_key, can point to a user written function that will be called when the menu manager encounters a key that is not defined. The declaration for bar_undef_key is as follows: unsigned int (*bar_undef_key)(BAR_MENU_PTR b, unsigned sel, unsigned int *choice) The user written function takes three arguments. The first argument is a pointer to the bar menu that the menu manager is currently processing. The second argument is an integer that contains the value of the key that was pressed. The third argument is a pointer to an integer that will contain the number of the menu choice to execute. Initially, choice points to an integer that contains the current menu choice that the menu highlight bar is situated. For instance, if the highlight bar is on the first menu choice when an undefined key is pressed, *choice will be equal to 1. If bar_undef_key is equal to a Null Function pointer (NULLFN), no user defined function is called. By default, bar_undef_key is assigned to NULLFN. Values returned to menu manager ------------------------------- If bar_undef_key is assigned to a function, the function must return an integer back to the menu manager. This integer value will tell the menu manager how to proceed. Here is a list of the valid return values that the user written function can return: Page 234 The C Window Library Page 234 Return Action to Value Take ------ --------- BAR_CONTINUE No Action. Continue processing the bar menu. BAR_DO_CHOICE Accept and invoke menu entry assigned to *choice. BAR_MOVE_CONTINUE Move the highlight bar to menu entry assigned to *choice and continue processing menu. BAR_ESCAPE Escape the bar menu. BAR_MOVE_LEFT Move to next bar menu. BAR_MOVE_RIGHT Move to previous bar menu. BAR_MOVE_HOME Move highlight to first available menu entry. BAR_MOVE_END Move highlight to last available menu entry. A return value of BAR_CONTINUE is a "do nothing" command to the menu manager. If BAR_DO_CHOICE is returned to the menu manager, the integer assigned to the parameter *choice is used as the menu entry to invoke. The highlight bar will automatically be moved to the menu choice specified, and the menu function will be called. If BAR_MOVE_CONTINUE is returned to the menu manager, the highlight bar will be moved to the entry specified by the value of *choice, but no function is called. Return values of BAR_DO_CHOICE and BAR_MOVE_CONTINUE only work when the menu entry specified by *choice is an available entry or the BAROVERRIDE option is on , otherwise the menu manager just continues processing the bar menu. Here is an example of using a user defined function for the undefined keys: #include "menu.h" /* Other includes */ int user_func(); Page 235 The C Window Library Page 235 main() { bar_undef_key = user_func; /* Other code */ } unsigned int user_func(BAR_MENU_PTR b, unsigned sel, unsigned *choice) { switch(sel) { case F1: help(*choice); /* call help function */ return BAR_CONTINUE; /* return "do nothing" command */ case F2: *choice = 6; /* do choice 6 on the menu */ return BAR_DO_CHOICE; default: return BAR_CONTINUE; /* let menu manager know not to do anything */ } } int help(int choice) { /* help function */ switch (choice) { case 1: /* do context-sensitive help for entry 1 */ break; case 2: /* do context-sensitive help for entry 2 */ break; /* do more entries */ /* ... */ } } In the above example, if the user hits F1, a help function is called. If you wanted to know how to incorporate a help function in the bar menus, here is the way to do it. If the user hits F2, the integer pointed to by choice is assigned a 6, and user_func() returns BAR_DO_CHOICE to the menu manager. This tells the menu manager to invoke the function assigned to menu entry 6. Page 236 The C Window Library Page 236 PRE-INPUT FUNCTION ------------------ With The C Window Library, you can define a function that will be performed just before the menu manager waits for the user to enter a keystroke. This function can perform just about anything. Setting the global_bar_prefunc function pointer ------------------------------------------------- The global_bar_prefunc function pointer points to this user written function. Here is the prototype: int (*global_bar_prefunc)(BAR_MENU_PTR p, unsigned *sel) The arguments that will be passed to your function are the following: a) The BAR_MENU_PTR of the bar menu that called your function, and b) A pointer to the number of the selection that the highlight bar is currently on. The selection number ranges from 1 to the highest entry number of the menu. The pre-input function MUST return a value back to the menu manager. The return values that can be returned are the same as the bar_undef_key function described above. If you are using a version of The C Window Library prior to version 1.5, you must declare your pre-input function as returning an int, and you must return a value back to the menu manager. Versions prior to 1.5 declared the pre-input function as void. The BAR_DO_CHOICE and BAR_MOVE_CONTINUE return values will move the highlight bar to the entry number that is assigned to the *sel argument when the pre-input function has returned. By default, global_bar_prefunc points to a NULLFN, and therefore will not be performed. However, you can implement pre-input functions depending on the current selection. For instance, you can write a function that displays extra information for each entry like so: #include "menu.h" char *mess[] = { " This option saves and loads files", " This brings you in edit mode", " This compiles and/or links the current program", Page 237 The C Window Library Page 237 /* ... More stuff */ }; WPOINTER message_window; int disp_info(); main() { /* ... */ global_bar_prefunc = disp_info; /* ... */ } int disp_info(BAR_MENU_PTR p, unsigned *sel) { /* Assume message_window already created and opened */ WindowClear(message_window, CREATE_VIDEO_ATTRIBUTE(black,white)); WindowWriteString(message_window,mess[*sel-1],1,1); return BAR_CONTINUE; } For simplicity, the menu definitions are left out of the preceding code sample. The disp_info displays the appropriate description in the window message_window. BAR_CONTINUE is returned to the menu manager. This informs the menu manager to continue looking for a keystroke. Page 238 The C Window Library Page 238 DISPOSING OF BAR MENUS ---------------------- BarMenuFree() function ---------------------- If the bar menu is no longer needed, the BarMenuFree() function will dispose of the bar menu and return any memory allocated to the bar menu, window, and window memory back to the heap. The call to the function is very simple: BarMenuFree(BAR_MENU_PTR b) where b is the BAR_MENU_PTR to dispose of. Since this function destroys the BAR_MENU_PTR b, b must not be used for any bar menu functions, unless b is pointing to a valid BAR_MENU_PTR. Return Values for BarMenuFree() ------------------------------- The return values and the reasons for failure are the same as BarSelectMenu(). Please refer to this section. Page 239 The C Window Library Page 239 PULLDOWN MENUS -------------- Description ----------- A pulldown menu is a combination of popup menus and a bar menu. The bar menu portion of the pulldown menu acts the same way as a normal bar menu. However when a choice is made from the bar menu, a popup menu appears with more options to choose. An example of a pulldown menu is the integrated environ- ments of the Quick C and Turbo C compilers. Most of what was discussed previously will apply to pulldown menus. Make sure that you have read the sections on popup menus and bar menus before preceding. Bar Menu and Popup Menu levels ------------------------------ With pulldown menus there are two levels; the bar menu level and the popup menu level. When in the bar menu level, no popup menu's are displayed, and the move right and move left keys move the highlight bar to the next or previous selection in the bar menu. When in the popup menu level, the move right and move left keys not only move the highlight in the bar menu, but will also display the popup menu associated with the bar menu option. Page 240 The C Window Library Page 240 CREATING PULLDOWN MENUS ----------------------- There are 4 steps that must be done when creating pulldown menus. They are as follows: Step 1) Create the bar menu portion by calling BarCreateMenu(). Step 2) Create each popup menu to be displayed underneath the bar by calling the PopupCreateMenu() function. Step 3) Group all popup menus created in step 2 into an array of popup menu's. Step 4) Call PulldownCreateMenu(). For Step 1) the bar menu is created the same way as described in the Bar Menu section of this manual. The only difference is that if there is a popup window that will be displayed under the bar menu option, the function pointer for that BAR_MENU_ENTRY must be a NULLFN (null integer function pointer). Otherwise, if there is no popup menu defined for that bar menu option, the BAR_MENU_ENTRY's function pointer must point to a valid function. For instance, here is a sample array of BAR_MENU_ENTRY's used to create the Turbo C integrated environments bar menu: BAR_MENU_ENTRY bar_items[] = { "File", 1,4, 'F',0,NULLFN, "Edit", 1,10,'E',0,menu_func, "Run", 1,17,'R',0,NULLFN, "Compile", 1,23,'C',0,NULLFN, "Project", 1,33,'P',0,NULLFN, "Options", 1,43,'O',0,NULLFN, "Debug", 1,53,'D',0,NULLFN, "Break/watch",1,61,'B',0,NULLFN, CWL_NULL}; In the above example, All of the entries have a NULLFN function pointer except for the "Edit" entry. The entries with NULLFN function pointers will have popup windows displayed under them when they are selected. The "Edit" option will not have a popup menu displayed under it. Instead, the menu_func() function is performed instead when "Edit" is chosen. Step 2) is as described in the Popup windows section. Page 241 The C Window Library Page 241 Step 3) can be done as follows: POPUP_MENU_PTR popup_list[8]; main() { /* ... */ popup_list[0] = PopupCreateMenu(/*..argument list..*/); popup_list[1] = (POPUP_MENU_PTR)0; /* No popup, so value must be NULL */ popup_list[2] = PopupCreateMenu(/*..argument list..*/); popup_list[3] = PopupCreateMenu(/*..argument list..*/); popup_list[4] = PopupCreateMenu(/*..argument list..*/); popup_list[5] = PopupCreateMenu(/*..argument list..*/); popup_list[6] = PopupCreateMenu(/*..argument list..*/); popup_list[7] = PopupCreateMenu(/*..argument list..*/); The above example shows each element of popup_list is assigned to the return value of PopupCreateMenu(), except for popup_list[1]. Note that popup_list[1] is a null POPUP_MENU_PTR. Here is the reason. Let's say that there is an option on the bar menu that DOES NOT have a popup menu associated with it. In other words, it is just a single function option, and no sub-functions are possible. The entry in the array of POPUP_MENU_PTR's that will correspond to the position of where there is no popup menu should be NULL. The above example shows that the second POPUP_MENU_PTR is non-existent (matches with the BAR_MENU_ENTRY called "Edit", which is the second bar entry). Once the bar menu and popup menus are created, you can set options by calling the BarSetOptions() or the PopupSetOptions() function, assign menu keys using the BarAssignKeys() or PopupAssignKeys() functions, etc. just as described earlier in this manual. Remember that a pulldown menu just incorporates all of your menus into one manageable entity. The PulldownCreateMenu() function --------------------------------- The next step (Step 4) is done by calling the PulldownCreateMenu() function. This function integrates the bar menu and the array of popup menus in a single unit. A pointer to this unit is returned. This pointer is declared as a PULLDOWN_MENU_PTR. The prototype form the PulldownCreateMenu() function is as follows: PULLDOWN_MENU_PTR PulldownCreateMenu(POPUP_MENU_PTR popups[], BAR_MENU_PTR bar, Page 242 The C Window Library Page 242 int adjust) The first argument is a pointer to an array of POPUP_MENU_PTR's. In the above example, the second argument is the BAR_MENU_PTR. Here is an example of how to use the PulldownCreateMenu() function: #include "menu.h" BAR_MENU_ENTRY bar_items[] = { "File", 1,4, 'F',0,NULLFN, "Edit", 1,10,'E',0,menu_func, "Run", 1,17,'R',0,NULLFN, "Compile", 1,23,'C',0,NULLFN, "Project", 1,33,'P',0,NULLFN, "Options", 1,43,'O',0,NULLFN, "Debug", 1,53,'D',0,NULLFN, "Break/watch",1,61,'B',0,NULLFN, CWL_NULL}; POPOP_MENU_ENTRY p1[] = { /* Popup entries */, CWL_NULL,0 }; POPUP_MENU_ENTRY p2[] = POPUP_NULL_ENTRY; /* This constant defines an empty POPUP_MENU_ENTRY */ POPUP_MENU_ENTRY p3[] = { /* More popup entries */ CWL_NULL, 0 }; POPUP_MENU_ENTRY p4[] = { /* More popup entries */ CWL_NULL, 0 }; POPUP_MENU_ENTRY p5[] = { /* More popup entries */ CWL_NULL, 0 }; POPUP_MENU_ENTRY p6[] = { /* More popup entries */ CWL_NULL, 0 }; POPUP_MENU_ENTRY p7[] = { /* More popup entries */ CWL_NULL, 0 }; POPUP_MENU_ENTRY p7[] = { /* More popup entries */ CWL_NULL, 0 }; POPUP_MENU_PTR popup_list[8]; Page 243 The C Window Library Page 243 BAR_MENU_PTR bar; PULLDOWN_MENU_PTR pull; main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); bar = BarCreateMenu(bar_items, { other arguments } ); popup_list[0] = PopupCreateMenu(p1, { other arguments } ); popup_list[1] = p2; popup_list[2] = PopupCreateMenu(p3, { other arguments } ); popup_list[3] = PopupCreateMenu(p4, { other arguments } ); popup_list[4] = PopupCreateMenu(p5, { other arguments } ); popup_list[5] = PopupCreateMenu(p6, { other arguments } ); popup_list[6] = PopupCreateMenu(p7, { other arguments } ); popup_list[7] = PopupCreateMenu(p8, { other arguments } ); pull = PulldownCreateMenu(popup_list,bar,1); {...} } In the above example, bar is a BAR_MENU_PTR, p1, p2, p3, p4, etc. are all lists of POPUP_MENU_ENTRY's. The array of POPUP_MENU_PTR's is called popup_list, and the PULLDOWN_MENU_PTR is called pull. Please note the use of the POPUP_NULL_ENTRY constant. Use this constant when initializing a POPUP_MENU_ENTRY list to no items. The bar menu is initialized by calling BarCreateMenu() using bar_items as the list of BAR_MENU_ENTRY's. The PopupCreateMenu() is called for each member of the popup_list array. Note that the popup_list[1] is assigned a null POPUP_MENU_PTR. This indicates that there is no popup menu for the second bar item ("Edit"). Even though it is not shown, you should check to see if BarCreateMenu() and all of the PopupCreateMenu() function calls returned without error. The call to PulldownCreateMenu() is done with the first argument being the the pointer to the array of POPUP_MENU_PTR's, namely popup_list. The second argument is the BAR_MENU_PTR bar, and the last argument is discussed in the next section. Automatic Adjustment of Popup Windows ------------------------------------- The last argument to PulldownCreateMenu() will inform the menu manager to adjust all the popup menu window positions, Page 244 The C Window Library Page 244 so that they fit neatly under the bar menu. If the adjust argument in PulldownCreateMenu() is a 1, the previous (row,col) positions of each popup menu window is ignored (Arguments 3 and 4 of PopupCreateMenu()), and the menu manager decides where the popup window should be placed on the screen. Otherwise, if adjust is 0, the previous values of the (row,col) position of the popup menu is used. Here is how the menu manager decides where the popup window should be placed: a) The first attempt tries to place the left hand corner of the popup window under the first character of the option name in the bar menu. If the column on the screen where we have placed the popup window, plus the popup windows width does not exceed the width of the bar, then we have found a "good" position for the popup window, if not then do step b). b) We place the upper right hand corner of the popup window underneath the last column of the bar menu's window. If the upper left-hand corner of the popup window can be placed in a screen column greater than or equal to 1, then we have found the "good" position. If the upper left-hand corner cannot be placed in column 1 then do step c). c) Place the upper left hand corner of the popup window at the first column of the bar menu window. If this does not work then do step d). d) place the popup window in column 1 of the screen. Here are a few examples of the above scenarios: 1) ------------------------------------------------------------- | File Edit Compile Options Project | | | ------------------------------------------------------------ | | |Condition a)| | worked! | | | |------------| Page 245 The C Window Library Page 245 2a) ---------------------------------------------------- | File Edit Compile Options Project | | | ------------------------------------------------------------ | | | Too wide! option a) failed! | | | | Try option b) | | | |--------------------------------| 2b) ------------------------------------------------------------- | File Edit Compile Options Project | | | ------------------------------------------------------------- | | | option b) worked! | | | |--------------------------------| In the first example, 1), the assumption is that the menu manager tries to place a popup window underneath the "File" in the bar menu. It satisfies condition a), so we have found a good position. In the second example, 2a), the assumption is that the menu manager is trying to place a popup window under the "Compile" in the bar menu. The first attempt fails because the popup window is too wide to be contained entirely in the bar menu. We then try again to see if condition b) can be satisfied. Example 2b) shows that we can place the popup window according to condition b), and we have found a good condition. The other conditions, c) and d) should be self-explanatory at this point. Remember, if you do not like the way the menu manager selects the window position, you can either a) specify the row and column positions of each popup menu window yourself when calling PopupCreateMenu(), and then calling PulldownCreateMenu() with a 0 (no adjustment) as the third argument or b) Let the menu manager decide where to put the windows, and then adjust the positions yourself by calling WindowMove(). Page 246 The C Window Library Page 246 Return values for PulldownCreateMenu() -------------------------------------- If there is no error, PulldownCreateMenu() returns a valid PULLDOWN_MENU_PTR. If there is an error, PulldownCreateMenu() returns a null PULLDOWN_MENU_PTR. Here are the possible reasons why an error has occurred: 1) There was not enough memory to allocate for the PULLDOWN_MENU_PTR or its internal data structures. 2) The window for the bar menu did not exist. The first error results from a lack of heap memory. If this error occurs, the global integer window_error_code will be set to NO_HEAP_MEM. If the second error occurs, this is an indication that the BAR_MENU_PTR was not created properly. Check the return values for BarCreateMenu() if this happens. The window_error_code is set to BAD_WINDOW if this error occurs. There is no check to see if the POPUP_MENU_PTR's are valid. It is conceivable that there may be some entries on the bar that do not have popup menu's under them. Therefore no check can be made for valid POPUP_WINDOW_PTR's. It is the programmer's responsibility to check for invalid POPUP_MENU_PTR's when creating the popup menus. Page 247 The C Window Library Page 247 SELECTING FROM PULLDOWN MENUS ----------------------------- The PulldownSelectMenu() function --------------------------------- The PulldownSelectMenu() allows selection from a pulldown menu. This function has 6 arguments. The prototype to this function is as follows: int PulldownSelectMenu(PULLDOWN_MENU_PTR pull, int barrank, unsigned barstart, int *poprank, unsigned *popstart, int imm) The first argument is a pointer to the PULLDOWN_MENU_PTR. The second argument is the window rank of the bar menu window. The third argument is the menu option where the bar menu should start beginning processing. If the option is invalid or unavailable, the starting entry is the first available entry or the first entry if the BAROVERRIDE option is on for the bar menu. The fourth argument is an array of window ranks for each popup menu's window. This array will correspond to each of the popup menu's windows, including null popup menus. Example: int ranks[] = {1,1,1,1,1,1,1,1}; unsigned start[] = {1,1,1,1,1,1,1,1}; main() { /* ... */ PulldownSelectMenu(pull,1,1,ranks,start,1); } The fifth argument is an array of starting entry numbers for each popup menu. This array will correspond to each of the popup menus, including NULL popup menus. The previous example illustrates how this could be done. Immediate Mode -------------- The last argument to PulldownSelectMenu() determines whether the menu will start in immediate mode. Immediate mode will display the bar menu, and will also display the popup menu defined for the bar option. If immediate mode is desired, the last argument is a 1, otherwise it is a 0. Page 248 The C Window Library Page 248 Values passed to the selected menu function ------------------------------------------- When a selection is made, the menu manager will call the function defined for the selection, and pass five arguments to this function. The first argument passed is the PULLDOWN_MENU_PTR of the current pulldown menu. The second argument is the BAR_MENU_PTR of the pulldown menu. The third argument is the POPUP_MENU_PTR of the selected entry. If there is no popup menu, the value passed for this argument is a NULL pointer. The fourth argument is the number of the item selected on the bar menu. The fifth argument is the number of the item selected on the popup menu. Values returned to the menu manager ----------------------------------- Your function must return a value back to the menu manager. There are two possible return values, PULLDOWN_EXIT and PULLDOWN_CONTINUE. The PULLDOWN_EXIT return value will cause the menu manager to close both the popup menu window (if one was displayed), and the bar menu. Then control is returned back to the function that called PulldownSelectMenu(). The PULLDOWN_CONTINUE return value will cause the menu manager to continue processing the pulldown menu without closing the popup window (if one was displayed). If the return value is not one of the ones mentioned above, PULLDOWN_CONTINUE is assumed. Return Values for PulldownSelectMenu() -------------------------------------- If there are no errors, PulldownSelectMenu() returns NO_ERROR. If the bar menu window does not exist, PulldownSelectMenu() immediately returns with BAD_WINDOW. If the bar menu window is not open, PulldownSelectMenu() immediately returns with WINDOW_NOT_OPEN. Page 249 The C Window Library Page 249 REDEFINING KEY DEFINITIONS -------------------------- The bar menu key definitions are invoked when the pulldown menu is at the bar menu level. The popup menu keys are invoked when the pulldown menu is at the popup menu level. If the bar option does not have a popup menu associated with it, the bar menu keys are always used. Page 250 The C Window Library Page 250 REDEFINING KEY DEFINITIONS FOR POPUP MENUS ------------------------------------------ Setting Popup Menu Global Key Definitions ----------------------------------------- In the previous sections on popup menus, there was a global array of key definitions used for popup menus. Recall that there were 3 key definitions that were not assigned. These definitions were POPUP_RIGHTKEY, POPUP_LEFTKEY, and POPUP_PULLDOWN_QUIT. When a popup menu is incorporated into a pulldown menu (after the PulldownCreateMenu() is called), the global array popup_key_definition is assigned the default values for these definitions. Here are the default values for the popup portion of the pulldown menu: Function Key Constant -------- --- ------ Move highlight bar up Up Arrow POPUP_UPKEY Move highlight bar down Down Arrow POPUP_DOWNKEY Accept Menu Choice Enter POPUP_ACCEPTKEY Escape Pop-up menu Escape POPUP_QUITKEY Move To First Menu Item Home POPUP_HOMEKEY Move to Last Menu Item End POPUP_ENDKEY Move To Next Popup Menu Right Arrow POPUP_RIGHTKEY Move to Previous Popup Menu Left Arrow POPUP_LEFTKEY Escape Pulldown Menu Unassigned POPUP_PULLDOWN_QUITKEY The global array popup_key_definition contains the values of the default popup menu key definitions. The names under the Constant heading are the offsets in the popup_key_definition array of where the key value for the function is defined. For instance, the value for the "Move highlight bar up" function is located at popup_key_definition[POPUP_UPKEY]. You can change the values in popup_key_definition at any time, but make sure that a definition for "Escape Pop-up menu" and/or "Escape Pulldown Menu" always exists, and that there are no duplicate definitions (i.e. the "Move highlight bar up" key definition is the same as the "Move highlight bar down" key definition). When defining new key values, you should use the values defined in the keycodes.h header file for non-ascii keys. Also note that popup_key_definition[POPUP_PULLDOWN_QUITKEY] is not assigned. Since the key that is usually used to quit a pulldown menu is the Escape (ESC) key, and this definition conflicts with the "Escape Popup menu", it is better to let the programmer change the definition explicitly. Page 251 The C Window Library Page 251 Setting Popup Menu Local Definitions ------------------------------------ You can use the PopupAssignKeys() function explained in the REDEFINING MENU KEYS section to redefine the popup menu keys for each popup menu. Page 252 The C Window Library Page 252 REDEFINING KEY DEFINITIONS FOR THE BAR MENU ------------------------------------------- Setting bar menu global key definitions --------------------------------------- You can redefine the keys used to control moving the highlight bar, accepting the menu choice, and exiting from the menu. Here is a list of the default key mapping: Function Key Constant -------- --- ------ Move highlight bar right Up Arrow BAR_RIGHTKEY Move highlight bar left Down Arrow BAR_LEFTKEY Accept Menu Choice Enter BAR_ACCEPTKEY Escape Bar menu or Escape BAR_QUITKEY Escape Pulldown Menu Move To First Menu Item Home BAR_HOMEKEY Move to Last Menu Item End BAR_ENDKEY The global array bar_key_definition contains the values of the default bar menu key definitions. The names under the Constant heading are the offsets in the bar_key_definition array of where the key value for the function is defined. For instance, the value for the "Move highlight bar up" function is located at bar_key_definition[BAR_RIGHTKEY]. You can change the values in bar_key_definition at any time, but make sure that a definition for "Escape Bar menu" always exists, and that there are no duplicate definitions (i.e. the "Move highlight bar up" key definition is the same as the "Move highlight bar down" key definition). When defining new key values, you should use the values defined in the keycodes.h header file for non-ascii keys. Note that "Escape Bar Menu" will also escape the pulldown menu. Setting Bar Menu Local definitions ---------------------------------- You can use the BarAssignKeys() function to redefine the bar menu keys. Page 253 The C Window Library Page 253 PROCESSING UNDEFINED POPUP MENU KEYS ------------------------------------ Processing undefined keys is the same for regular popup menus, except that there are 3 new return values that can be used for popup menus that are incorporated in pulldown menus. The popup_undef_key function pointer acts the same way as described previously. Here are the possible values that the function pointed to by popup_undef_key must return: Return Action to Value Take ------ --------- POPUP_CONTINUE No Action. Continue processing the popup menu. POPUP_MOVE_UP Move the highlight bar up. POPUP_MOVE_DOWN Move the highlight bar down. POPUP_DO_CHOICE Accept and invoke menu entry assigned to *choice. POPUP_MOVE_CONTINUE Move the highlight bar to menu entry assigned to *choice and continue processing menu. POPUP_ESCAPE Escape the popup menu. POPUP_MOVE_HOME Move highlight to first available menu entry. POPUP_MOVE_END Move highlight to last available menu entry. POPUP_MOVE_PAGEUP Scroll the entries in the popup window up by one "page" (a page is the current height of the popup window). POPUP_MOVE_PAGEDOWN Scroll the entries in the popup window down by one "page" (a page is the current height of the popup window). POPUP_MOVE_LEFT Move to next popup menu. POPUP_MOVE_RIGHT Move to previous popup menu. POPUP_PULLDOWN_QUIT Escape pulldown menu Please note the new return values POPUP_MOVE_LEFT, POPUP_MOVE_RIGHT, and POPUP_PULLDOWN_QUIT. Page 254 The C Window Library Page 254 PROCESSING UNDEFINED BAR MENU KEYS ---------------------------------- Here are the return values that the function pointed to by bar_undef_key must return. Return Action to Value Take ------ --------- BAR_CONTINUE No Action. Continue processing the bar menu. BAR_DO_CHOICE Accept and invoke menu entry assigned to *choice, or display popup menu underneath bar entry. BAR_MOVE_CONTINUE Move the highlight bar to menu entry assigned to *choice and continue processing menu. BAR_ESCAPE Escape the bar menu (or pulldown menu). BAR_MOVE_LEFT Move to next bar menu entry. BAR_MOVE_RIGHT Move to previous bar menu entry. BAR_MOVE_HOME Move highlight to first available menu entry. BAR_MOVE_END Move highlight to last available menu entry. Please note that BAR_DO_CHOICE will either do the function assigned to the bar entry assigned to *choice, or display the popup menu underneath the bar menu entry assigned to *choice. Page 255 The C Window Library Page 255 DISPOSING OF PULLDOWN MENUS --------------------------- There are two functions that are used to dispose of pulldown menus. The first is the PulldownMenuFree() function. The PulldownMenuFree() function ------------------------------- The PulldownMenuFree() function disposes of the PULLDOWN_MENU_PTR and returns memory allocated back to the heap. The bar menu and the popup menus associated with the pulldown menu remain intact. Here is a prototype of the call to PulldownMenuFree(): int PulldownMenuFree(PULLDOWN_MENU_PTR pull) The PulldownMenuFreeAll() function ---------------------------------- To dispose of the pulldown menu, the bar menu, and all of the popup menus, use the PulldownMenuFreeAll() function. Here is a prototype: int PulldownMenuFreeAll(PULLDOWN_MENU_PTR pull) Page 256 The C Window Library Page 256 SUMMARY OF PULLDOWN MENUS ------------------------- A pulldown menu is: 1) Made up of a bar menu and popup menus. 2) Consists of two levels, namely the bar menu level and the popup menu level. 3) The bar menu level uses the bar menu key definitions, while the popup menu level uses the popup menu key definitions. 4) The popup menus are initialized by using an array of POPUP_MENU_PTR's. The order of where the popup menus are defined in this array corresponds to each of the bar menu options. 5) A bar menu option may or may not have a popup menu defined for it. 6) When initializing a pulldown menu, you can allow the menu manager to position the popup windows under the bar menu, or you can specify your own positions on the screen for the popup menu windows. 7) When the menu manager calls the user written function the PULLDOWN_MENU_PTR, BAR_MENU_PTR, POPUP_MENU_PTR, the number of the bar entry selected, and the number of the popup selection are passed to the user function. If there is no popup menu, the POPUP_MENU_PTR passed is a null, and the popup selection number is 0. 8) You can open a pulldown menu from the bar level, or from the pull down level by calling PulldownSelectMenu(). 9) You can close a pulldown menu in two ways: by just disposing of the PULLDOWN_MENU_PTR by calling PulldownMenuFree(), or disposing of all menus used to create the pulldown menu by calling PulldownMenuFreeAll(). Page 257 The C Window Library Page 257 EXAMPLE OF PULLDOWN MENU SYSTEM ------------------------------- Here is an example of a pulldown menu system. This program emulates the Turbo C integrated environment. #include "menu.h" #define BLACKONWHITE CREATE_VIDEO_ATTRIBUTE(white,black) int menu_routine(); POPUP_MENU_ENTRY menu_items1[] = { " Load F3",1,'L',F3,menu_routine, " Pick Alt-F3",2, 'P',ALTF3,menu_routine, " New" ,3, 'N',0,menu_routine, " Save F2",4, 'S',F2,menu_routine, " Write to ",5, 'W',0,menu_routine, " Directory ",6, 'D',0,menu_routine, " Change Dir" ,7, 'C',0,menu_routine, " OS shell" ,8, 'O',0,menu_routine, " Quit Alt-X" ,9,'Q',ALTX,menu_routine, CWL_NULL,0}; POPUP_MENU_ENTRY menu_items3[] = { " Run Ctrl-F9 ",1,'R',CTRLF9,menu_routine, " Program reset Ctrl-F2 ",2,'P',CTRLF2,menu_routine, " Go to Cursor F4 ",3,'G',F4,menu_routine, " Trace into F7 ",4,'T',F7,menu_routine, " Step over F8 ",5,'S',F8,menu_routine, " User screen Alt-F5 ",6,'U',ALTF5,menu_routine, CWL_NULL,0}; POPUP_MENU_ENTRY menu_items4[] = { " Compile to OBJ ",1,'C',0,menu_routine, " Make EXE file ",2,'M',0,menu_routine, " Link EXE file ",3,'L',0,menu_routine, " Build all ",4,'B',0,menu_routine, " Primary C file: ",5,'P',0,menu_routine, " Get info ",6,'G',0,menu_routine, CWL_NULL,0}; POPUP_MENU_ENTRY menu_items5[] = { " Project Name ",1,'P',0,menu_routine, " Break make on ",2,'B',0,menu_routine, " Auto dependencies ",3,'A',0,menu_routine, " Clear project ",4,'C',0,menu_routine, " Remove messages ",5,'R',0,menu_routine, CWL_NULL,0}; Page 258 The C Window Library Page 258 POPUP_MENU_ENTRY menu_items6[] = { " Compiler ",1,'C',0,menu_routine, " Linker ",2,'L',0,menu_routine, " Environment ",3,'E',0,menu_routine, " Directories ",4,'D',0,menu_routine, " Arguments ",5,'A',0,menu_routine, " Save Options ",6,'S',0,menu_routine, " Retrieve options ",7,'R',0,menu_routine, CWL_NULL,0}; POPUP_MENU_ENTRY menu_items7[] = { " Evaluate Ctrl-F4 ",1,'E',CTRLF4,menu_routine, " Call Stack Ctrl-F3 ",2,'C',CTRLF3,menu_routine, " Find Function ",3,'F',0,menu_routine, " Refresh display ",4,'R',0,menu_routine, " Display swapping Smart ",5,'D',0,menu_routine, " Source debugging ",6,'S',0,menu_routine, CWL_NULL,0}; POPUP_MENU_ENTRY menu_items8[] = { " Add watch Ctrl-F7 ",1,'A',CTRLF7,menu_routine, " Delete watch ",2,'D',0,menu_routine, " Edit Watch ",3,'E',0,menu_routine, " Remove all watches ",4,'R',0,menu_routine, " Toggle breakpoint Ctrl-F8 ",6,'T',CTRLF8,menu_routine, " Clear all breakpoints ",7,'C',0,menu_routine, " View next breakpoint ",8,'V',0,menu_routine, CWL_NULL,0}; BAR_MENU_ENTRY bar_items[] = { "File",1,4,'F',0,NULLFN, "Edit",1,10,'E',0,menu_routine, "Run",1,17,'R',0,NULLFN, "Compile",1,23,'C',0,NULLFN, "Project",1,33,'P',0,NULLFN, "Options", 1,43,'O',0,NULLFN, "Debug",1,53,'D',0,NULLFN, "Break/watch",1,61,'B',0,NULLFN, CWL_NULL}; POPUP_MENU_ENTRY *pentry[] = {menu_items1, POPUP_NULL_ENTRY, menu_items3, menu_items4, menu_items5, menu_items6, menu_items7, menu_items8}; unsigned menu_colors[5]; /* Menu colors */ BAR_MENU_PTR bar; /* Pointer to bar menu */ POPUP_MENU_PTR popups[8]; /* Array of pointers to Page 259 The C Window Library Page 259 popup menus */ PULLDOWN_MENU_PTR pull; /* Pointer to pulldown menu */ WPOINTER my_open(); /* Pointer to custom bar window open function */ unsigned int popuprank[] = {1,1,1,1,1,1,1,1}; /* Ranks */ int popupstart[] = {1,1,1,1,1,1,1,1}; /* Starting option for each popup menu */ int height[] = {9,0,6,6,5,7,6,8}; /* height of each window */ WPOINTER pw; /* Misc. windows, not part of menu system */ char *line = "─────────────────────────────"; /* Horizontal line */ main() { int i; WindowInitializeSystem(); WindowSaveInitial(0); pw = WindowInitialize(BORDER,5,10,70,5,BLACKONWHITE, BLACKONWHITE,SINGLEBOX); WindowOpen(pw); /* define colors */ menu_colors[0] = CREATE_VIDEO_ATTRIBUTE(white,black); menu_colors[1] = CREATE_VIDEO_ATTRIBUTE(white,black); menu_colors[2] = CREATE_VIDEO_ATTRIBUTE(white,blue); menu_colors[3] = CREATE_VIDEO_ATTRIBUTE(cyan,black); menu_colors[4] = CREATE_VIDEO_ATTRIBUTE(white,black); bar = BarCreateMenu(bar_items,menu_colors,6,1, BARWRAP | BARSTATIC, my_open); /* Now loop to create all popup menus Be careful and assign NULL to the second popup menu */ for (i=0; i<8; i++) /* Loop for all popup menus */ { if (pentry[i] != POPUP_NULL_ENTRY) /* Skip over NULL */ { popups[i] = PopupCreateMenu(pentry[i], menu_colors, 1, 1, height[i], POPUPWRAP | POPUPSTATIC, WNULLFN, VWNULLFN); } else popups[i] = (POPUP_MENU_PTR)0; /* Make this a null POPUP_MENU_PTR */ Page 260 The C Window Library Page 260 } /* end for (i=0 ... */ VirtualWriteString(POPUP_VIRTUAL_WINDOW(popups[7]),line, 5,1); /* hide 2nd and 3rd entries in */ PopupMakeEntryUnavailable(popups[6],2); PopupMakeEntryUnavailable(popups[6],3); /* puit override option on number 6 */ PopupSetOptions(popups[6],POPUPOVERRIDE,1); /* create pulldown menu */ pull = PulldownCreateMenu(popups,bar,1); /* get the menu options */ PulldownSelectMenu(pull,1,1,popuprank,popupstart,1); /* dispose of menu */ PulldownMenuFree(pull); } int menu_routine(PULLDOWN_MENU_PTR p, BAR_MENU_PTR b, POPUP_MENU_PTR pop, unsigned int hs, unsigned int vs) { int ch; WindowClear(pw); WindowPrintf(pw, "You have selected bar option %s\npopup option %s\n", BAR_ENTRY_STRING(b,hs),POPUP_ENTRY_STRING(pop,vs)); WindowWriteCenterString(pw,"Press Escape to Quit",3); WindowWriteCenterString(pw, "Press any other key to continue...",4); WindowDisplay(pw,1,NOEFFECT); ch = GET_KEY(); WindowHide(pw,NOEFFECT); if (ch == ESC) return PULLDOWN_EXIT; return PULLDOWN_CONTINUE; } WPOINTER my_open() /* Custom window open function */ { WPOINTER w; w = WindowInitialize(NOBORDER,1,1,80,1,BLACKONWHITE, BLACKONWHITE,""); WindowOpen(w); return w; } Page 261 The C Window Library Page 261 MISCELLANEOUS FUNCTIONS ----------------------- There are other functions in The C Window Library that you can use without defining windows. SETTING AND CHECKING VIDEO PAGES -------------------------------- The following functions sets and checks video pages. Your video setup must support multiple video pages for the examples given in this section to work. Please refer to page 5 for a discussion of video adapters and the number of pages each will support. CheckVideoPage() ---------------- This function checks to see if the video page is valid. Here is the prototype: int CheckVideoPage(int page) If page is valid, CheckVideoPage() returns NO_ERROR. If it is not, the return value is INVALID_PAGE. Example: #include "window.h" main() { int i; WindowInitializeSystem(); for (i=0;i<8;i++) { if (CheckVideoPage(i) == NO_ERROR) printf("\nValid video page #%d",i); else printf("\nInvalid video page #%d",i); } } Page 262 The C Window Library Page 262 SetActiveVideoPage() function ----------------------------- The SetActiveVideoPage() function sets the active video page. Here is a prototype: int SetActiveVideoPage(int page) Any windows initialized with WindowInitialize() will have its output directed to the current active video page on initialization. This function DOES NOT change the visible display page. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w1, w2; main() { WindowInitializeSystem(); /* Save Base Screen for video pages 0 and 1 */ WindowSaveInitial(0); WindowSaveInitial(1); /* Set the active video page */ SetActiveVideoPage(0); w1 = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX); SetActiveVideoPage(1); w2 = WindowInitialize(BORDER,1,1,10,10,NORM,NORM,SINGLEBOX); } The above example shows two windows, w1 and w2, being open on different video pages. Please note the two calls to WindowSaveInitial(). The first saves the base screen on video page 0, and the second call saves the initial screen on page 1. The first call to SetActiveVideoPage() sets the active video page to page 0. This is usually the active video page on startup. Since the active page is 0, w1 is opened with page 0 as its video page. The second call to SetActiveVideoPage() makes page 1 the active page, therefore w2 is initialized to send its output to video page 1. If there are no errors, SetActiveVideoPage() returns NO_ERROR. If there are errors, SetActiveVideoPage() returns INVALID_PAGE if the video page is invalid. Page 263 The C Window Library Page 263 SetVisibleVideoPage() function ------------------------------ The SetVisibleVideoPage() function sets the visible video page. Here is a prototype: int SetVisibleVideoPage(int page) The visible video page is the page displayed on the screen. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w1,w2; main() { WindowInitializeSystem(); /* Make sure video page is 0 */ SetVisibleVideoPage(0); SetActiveVideoPage(0); /*Save Base screen for video pages 0 and 1 */ WindowSaveInitial(0); WindowSaveInitial(1); /* Initialize Windows */ w1 = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); SetActiveVideoPage(1); w2 = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); WindowOpen(w1); WindowOpen(w2); WindowWriteString(w1,"This is window 1 on page 0",1,1); WindowWriteString(w2,"This is window 2 on page 1",1,1); /* Display video page 0 */ WindowDisplay(w1,1,NOEFFECT); GET_KEY(); /* Change to video page 1 and display */ SetVisibleVideoPage(1); WindowDisplay(w2,1,NOEFFECT); GET_KEY(); /* Reset to page 0 */ SetVisibleVideoPage(0); } The example above initializes two windows. w1 is initialized on page 0 and w2 is initialized on page 1. Also note that Page 264 The C Window Library Page 264 there are two calls to WindowSaveInitial(), one for page 0 and another for page 1. The first window displayed is w1. Once a key is pressed the visible page is switched to page 1 by calling SetVisibleVideoPage(). The last line of the program sets the visible page back to page 0. You should do this on exit of any program that changes video pages. If there are no errors, SetVisibleVideoPage() returns NO_ERROR. If there are errors, SetVisibleVideoPage() returns INVALID_PAGE if the video page is invalid. Page 265 The C Window Library Page 265 GENERAL STRING WRITING FUNCTIONS -------------------------------- The following functions write strings to the active video page. These functions are not window functions, therefore you should use these functions when you are not using windows created with The C Window Library unless you are careful in using them. The advantage of using these functions instead of the normal string writing functions found in most C compiler libraries (i.e. printf(), puts(), etc.) is that the output is written directly to screen memory, which results in fast output. If the BIOS option is selected, BIOS functions are used to write the strings. Refer to page 4 for a discussion of direct screen writing and BIOS functions. VideoWriteString() ------------------ This function writes a null terminated string to the active video page. Here is the prototype: void VideoWriteString(char *string, int row, int col) The first argument is the string, and the second and third arguments are the (row,col) position of the active video page to place the string. There is no check to see if (row,col) is out of bounds. The attribute that is used is determined by the current video attribute at each character position on the screen. Example: #include "window.h" main() { int i; WindowInitializeSystem(); for (i=1;i<=10;i++) VideoWriteString("Hello, World",i,1); } There is no return value for VideoWriteString(). Page 266 The C Window Library Page 266 VideoWriteStringAttr() ---------------------- This function writes a null terminated string to the active video page using a video attribute. Here is the prototype: void VideoWriteStringAttr(char *string, int row, int col, int attr) The first argument is the string, the second and third arguments are the (row,col) position of the active video page to place the string, and the last argument is the video attribute to use. There is no check to see if (row,col) is out of bounds. The last argument is the video attribute to use. Example: #include "window.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) main() { int i; WindowInitializeSystem(); for (i=1;i<=10;i++) VideoWriteStringAttr("Hello, World",i,1,REVERSE); } There is no return value for VideoWriteStringAttr(). VideoWriteAttributes() ---------------------- This function writes a string of attributes to the active video page. Here is the prototype: void VideoWriteAttributes(char *buffer, int row, int col, int num) The first argument is the buffer that contains the video attributes. The second and third arguments are the (row,col) position of the active video page to place the attributes, and the last arguments is the number of attributes to write from the buffer. There is no check to see if (row,col) is out of bounds, or if num attributes will exceed the right edge of the screen. Page 267 The C Window Library Page 267 Example: #include "window.h" #include <string.h> #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) char buf[12]; main() { WindowInitializeSystem(); VideoWriteString("Hello, World",1,1); GET_KEY(); memset(buf,REVERSE,sizeof(buf)); VideoWriteAttributes(buf,1,1,sizeof(buf)); } The example above writes a string using the VideoWriteString() function and then changes the attribute of the string by setting a buffer to the REVERSE attribute and using the VideoWriteAttributes() function with this buffer. There is no return value for VideoWriteAttributes(). VideoWriteCenterString() ------------------------ The VideoWriteCenterString() function centers a string at a certain row of the active video page. Here is the prototype: void VideoWriteCenterString(char *string, int row) The first argument is the string and the second argument is the row to write on the active video page to write the string. There is no check to see if row is out of bounds. Example: #include "window.h" main() { int i; WindowInitializeSystem(); for (i=1;i<=10;i++) VideoWriteCenterString("Hello, World",i); } There is no return value for VideoWriteCenterString(). Page 268 The C Window Library Page 268 VideoWriteCenterStringAttr() ---------------------------- The VideoWriteCenterStringAttr() function centers a string at a certain row of the active video page with a specified video attribute. Here is the prototype: void VideoWriteCenterStringAttr(char *string, int row, int attr) The first argument is the string and the second argument is the row to write on the active video page to write the string. The third argument is the video attribute to use. There is no check to see if row is out of bounds. Example: #include "window.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) main() { int i; WindowInitializeSystem(); for (i=1;i<=10;i++) VideoWriteCenterStringAttr("Hello, World",i,REVERSE); } There is no return value for VideoWriteCenterStringAttr(). VideoWriteCharAndAttr() ----------------------- The VideoWriteCharAndAttr() function writes a string of character-attribute pairs to the active video page. Here is the prototype: void VideoWriteCharAndAttr(char *buffer, int row, int col, int num) The first argument is the buffer that holds the character attribute pairs. This buffer should be in the following form: ----------------------------------------------- |char1 | attr1 | char2 | attr2 | char3 | attr3| ... ----------------------------------------------- The second and third arguments are the (row,col) position of the active video page to write the string. The last argument Page 269 The C Window Library Page 269 is the number of character-attribute pairs to write. Example: #include "window.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) char buf[24]; main() { int i,j; WindowInitializeSystem(); for (i=0,j='A'; i<24; i+=2,j++) { buf[i] = j; buf[i+1] = REVERSE; } for (i=1;i<=10;i++) VideoWriteCharAndAttr(buf,i,1,12); } The example above creates a string of character attribute pairs and then writes this string using the VideoWriteCharAndAttr() function. There is no return value for VideoWriteCharAndAttr(). VideoWriteStringCC() -------------------- This function writes a string centered around a column on the active video page. Here is the prototype: void VideoWriteStringCC(char *string, int row, int col) The first argument is the string. The second argument is the row, and the third argument is the column to center the string around. Example: #include "window.h" main() { int i; WindowInitializeSystem(); VideoWriteStringCC("This",1,10); VideoWriteStringCC("is",2,10); VideoWriteStringCC("centered",3,10); VideoWriteStringCC("around",4,10); VideoWriteStringCC("column",5,10); VideoWriteStringCC("10",6,10); } Page 270 The C Window Library Page 270 There is no return value for VideoWriteStringCC(). VideoWriteStringCCAttr() ------------------------ This function writes a string centered around a column on the active video page with a specified video attribute. Here is the prototype: void VideoWriteStringCCAttr(char *string, int row, int col, int attr) The first argument is the string. The second argument is the row. The third argument is the column to center the string around, and the fourth argument is the attribute to use. Example: #include "window.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) main() { int i; WindowInitializeSystem(); VideoWriteStringCCAttr("This",1,10,REVERSE); VideoWriteStringCCAttr("is",2,10,REVERSE); VideoWriteStringCCAttr("centered",3,10,REVERSE); VideoWriteStringCCAttr("around",4,10,REVERSE); VideoWriteStringCCAttr("column",5,10,REVERSE); VideoWriteStringCCAttr("10",6,10,REVERSE); } There is no return value for VideoWriteStringCCAttr(). VideoWriteStringRJ() -------------------- The VideoWriteStringRJ() function writes a string to the screen that is right justified at column col. If the string will not fit within column 1, the string is still right justified, but excess characters to the left of column 1 are clipped. This function writes a string column on the active video page. Here is the prototype: void VideoWriteStringRJ(char *string, int row, int col) The first argument is the string. The second argument is the row, and the third argument is the column to right justify the string on. Page 271 The C Window Library Page 271 Example: #include "window.h" main() { int i; WindowInitializeSystem(); VideoWriteStringRJ("This",1,10); VideoWriteStringRJ("is",2,10); VideoWriteStringRJ("right",3,10); VideoWriteStringRJ("justified",4,10); VideoWriteStringRJ("on ",5,10); VideoWriteStringRJ("column",6,10); VideoWriteStringRJ("10",7,10); } There is no return value for VideoWriteStringRJ(). VideoWriteStringRJAttr() ------------------------ The VideoWriteStringRJAttr() function writes a string to the screen that is right justified at column col with a specified video attribute. If the string will not fit within column 1, the string is still right justified, but excess characters to the left of column 1 are clipped. This function writes a string column on the active video page. Here is the prototype: void VideoWriteStringRJAttr(char *string, int row, int col, int attr) The first argument is the string. The second argument is the row. The third argument is the column to right justify the string on, and the last argument is the video attribute to use. Example: #include "window.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) main() { int i; WindowInitializeSystem(); VideoWriteStringRJAttr("This",1,10,REVERSE); VideoWriteStringRJAttr("is",2,10,REVERSE); VideoWriteStringRJAttr("right",3,10,REVERSE); VideoWriteStringRJAttr("justified",4,10,REVERSE); VideoWriteStringRJAttr("on ",5,10,REVERSE); VideoWriteStringRJAttr("column",6,10,REVERSE); VideoWriteStringRJAttr("10",7,10,REVERSE); } Page 272 The C Window Library Page 272 There is no return value for VideoWriteStringRJAttr(). VideoPrintf() ------------- The VideoPrintf() function writes formatted strings to the active video page. This function works exactly the same as printf() except that output is written directly to the screen. Here is the prototype: void VideoPrintf(char *format [,arg1,arg2...]) The location of the output is placed at the current cursor position. The cursor is advanced to one character beyond the last character of output. Example: #include "window.h" int i = 3; double j = 5.6; main() { WindowInitializeSystem(); VideoPrintf("3+2 is equal to %d\n",3+2); VideoPrintf("i is equal to %d\nj is equal to %lf\n",i,j); } Unlike printf(), there is no return value with VideoPrintf(). VideoPrintfAttr() ----------------- The VideoPrintfAttr() function works the same as VideoPrintf() except that a video attribute is specified. Here is the prototype: void VideoPrintfAttr(int attr, char *format [,arg1,arg2...]) The first argument is the attribute to use. The second argument is the format string, and the other arguments are optional arguments. Page 273 The C Window Library Page 273 Example: #include "window.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(white,black) int i = 3; double j = 5.6; main() { WindowInitializeSystem(); VideoPrintfAttr(REVERSE,"3+2 is equal to %d\n",3+2); VideoPrintfAttr(REVERSE, "i is equal to %d\nj is equal to %lf\n",i,j); } Unlike printf(), there is no return value with VideoPrintfAttr(). Page 274 The C Window Library Page 274 READING CHARACTERS AND ATTRIBUTES FROM THE SCREEN ------------------------------------------------- These functions read characters and/or attributes from the active video page. VideoReadCharacters() --------------------- This function reads characters from the active video page into a buffer. Here is the prototype: void VideoReadCharacters(char *buffer, int row, int col, int num) The first argument is the buffer to store the characters. The second and third arguments are the (row,col) position on the active video page. The last argument is the number of characters to read in. There is no check to see if the row, col, or the num arguments are in bounds of the screen. Example: #include "window.h" char buf[25]; main() { WindowInitializeSystem(); VideoReadCharacters(buf,1,1,25); } The example above reads the characters on the screen starting at position (1,1). There is no return value for VideoReadCharacters(). VideoReadAttributes() --------------------- This function reads attributes from the active video page into a buffer. Here is the prototype: void VideoReadAttributes(char *buffer, int row, int col, int num) The first argument is the buffer to store the attributes. The second and third arguments are the (row,col) position on Page 275 The C Window Library Page 275 the active video page. The last argument is the number of attributes to read in. There is no check to see if the row, col, or the num arguments are in bounds of the screen. Example: #include "window.h" char buf[25]; main() { WindowInitializeSystem(); VideoReadAttributes(buf,1,1,25); } The example above reads the attributes on the screen starting at position (1,1). There is no return value for VideoReadAttributes(). VideoReadCharAndAttr() ---------------------- This function reads character-attribute pairs from the active video page into a buffer. Here is the prototype: void VideoReadCharAndAttr(char *buffer, int row, int col, int num) The first argument is the buffer to store the character-attribute pairs. The second and third arguments are the (row,col) position on the active video page. The last argument is the number of character-attribute pairs to read in. There is no check to see if the row, col, or the num arguments are in bounds of the screen. Example: #include "window.h" char buf[26]; main() { WindowInitializeSystem(); VideoReadCharAndAttr(buf,1,1,13); } The example above reads the character-attribute pairs on the screen starting at position (1,1). There is no return value for VideoReadCharAndAttr(). Page 276 The C Window Library Page 276 DRAWING BOXES ------------- The following functions draw boxes on the screen. VideoDrawBox() -------------- The VideoDrawBox() function draws a box on the screen. Here is the prototype: void VideoDrawBox(int urow, int ucol, int lrow, int lcol, char *boxchars) The box is defined by a rectangular region. The urow and ucol arguments are the coordinates of the upper left hand corner of the box. The lrow and lcol arguments are the coordinates of the lower right hand corner of the box. The last argument is a string of box drawing characters to use. You can use the predefined box types in the header file vidsys.h, or you can make your own. Refer to page 11 for more information on box types. There is no check to see if the coordinates are in bounds. Example: #include "window.h" main() { WindowInitializeSystem(); ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white)); /* Draw two boxes */ VideoDrawBox(1,1,10,10,SINGLEBOX); VideoDrawBox(1,11,10,21,DOUBLEBOX); } There is no return value for VideoDrawBox(). VideoDrawBoxAttr() ------------------ The VideoDrawBoxAttr() function draws a box on the screen with a specified video attribute. Here is the prototype: void VideoDrawBoxAttr(int urow, int ucol, int lrow, int lcol, char *boxchars, int attr) This function works the same way as the VideoDrawBox() function. Note that the last argument is the video attribute Page 277 The C Window Library Page 277 to use. There is no check to see if the coordinates are in bounds. Example: #include "window.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(black,white) main() { WindowInitializeSystem(); ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white)); /* Draw two boxes */ VideoDrawBoxAttr(1,1,10,10,SINGLEBOX,REVERSE); VideoDrawBoxAttr(1,11,10,21,DOUBLEBOX,REVERSE); } There is no return value for VideoDrawBoxAttr(). Page 278 The C Window Library Page 278 SAVING AND RESTORING SCREEN IMAGES ---------------------------------- The following functions save rectangular regions of the screen in a buffer, and restore rectangular portions of the screen. These routines exist in The C Window Library so that advanced C programmers can have general screen saving/restoring routines handy. As always, you should be careful in using these functions at the same time you are using windows created with The C Window Library. VideoSave() ----------- The VideoSave() function saves a rectangular portion of the screen into a structure called a VBLOCK. A pointer to this structure is called a VBLOCKPTR. Here is the prototype: VBLOCKPTR VideoSave(int urow, int ucol, int lrow, int lcol) This function returns a VBLOCKPTR. The VBLOCKPTR will be used to move or restore this saved region. The first two arguments are the coordinates of the upper left hand corner of the rectangle to save (urow,ucol). The last two arguments are the coordinates of the lower right hand corner of the rectangle (lrow,lcol). There is no check to see if the coordinates are out of bounds. You can use this function to save the base screen, and then use VideoRestore() to restore the base screen on exit. Example: #include "window.h" VBLOCKPTR v; main() { WindowInitializeSystem(); v = VideoSave(1,1,25,80); /* Save Rectangular region */ /* Check if NULL */ if (v == (VBLOCKPTR)0) VideoWriteString("Trouble saving video"); } If there are no errors, VideoSave() returns a valid VBLOCKPTR. If there are errors VideoSave() returns a null VBLOCKPTR and sets the global integer window_error_code to the following value: NO_HEAP_MEM if there is not enough memory for the save buffer of the VBLOCKPTR. Page 279 The C Window Library Page 279 VideoMove() ----------- The VideoMove() function moves a region saved by VideoSave() to a different location of the screen. This location will be the new upper left hand corner of the rectangular region that was saved. The move is not displayed until you call VideoRestore(), which is defined later. Here is the prototype: void VideoMove(VBLOCKPTR v, int row, int col) The first argument is the VBLOCKPTR. The second and third arguments are the new upper left hand position of the saved area. There is NO check to see if the VBLOCKPTR exists, or the row or column are valid. Example: #include "window.h" VBLOCKPTR v; main() { WindowInitializeSystem(); v = VideoSave(1,1,10,10); /* Save Rectangular region defined by (1,1) (10,10) */ VideoMove(v,1,10); } There is no return value for VideoMove(). VideoRestore() -------------- The VideoRestore() function takes a rectangular area of the screen saved with VideoSave() and redisplays the area. Here is the prototype: void VideoRestore(VBLOCKPTR v) The only argument is the VBLOCKPTR. There is no check to see if the VBLOCKPTR is valid. Example: #include "window.h" VBLOCKPTR v; Page 280 The C Window Library Page 280 main() { WindowInitializeSystem(); v = VideoSave(1,1,10,10); for (i=1;i<=10;i++) VideoWriteString("This is the save area. " "Press a key to restore.",i,1); GET_KEY(); VideoRestore(v); } There is no return value for VideoRestore(). VideoFree() ----------- The VideoFree() function frees a previously defined VBLOCKPTR. Here is the prototype: void VideoFree(VBLOCKPTR v) The only argument is the VBLOCKPTR. There is NO check to see if the VBLOCKPTR is valid, therefore you must be very careful to call this function on a valid VBLOCKPTR. If not, the heap will become corrupted. Example: #include "window.h" VBLOCKPTR v; main() { WindowInitializeSystem(); v = VideoSave(1,1,10,10); for (i=1;i<=10;i++) VideoWriteString("This is the save area. " "Press a key to restore.",i,1); GET_KEY(); VideoRestore(v); VideoFree(v); } There is no return value for VideoFree(). Page 281 The C Window Library Page 281 CLEARING SCREENS ---------------- The following functions clears the visible video page, and clears regions of the visible screen. ClearScreen() ------------- The ClearScreen() function clears the visible video page with a specified attribute and moves the screen cursor to position (1,1). Here is the prototype: void ClearScreen(int attr) The only argument is the video attribute to use. Example: #include "window.h" main() { WindowInitializeSystem(); /* Clear the entire screen */ ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white)); } There is no return value for ClearScreen(). ClearRegion() ------------- This function clears a rectangular region of the screen. Here is the prototype: void ClearRegion(int urow, int ucol, int lrow, int lcol, int attr) The first two arguments represent the coordinate of the upper left hand coordinates of the rectangular region to clear. The third and fourth arguments represent the coordinate of the lower right hand corner of the rectangular region. The last argument is the attribute to use. There is no check to see if the coordinates are in bounds. Page 282 The C Window Library Page 282 Example: #include "window.h" main() { WindowInitializeSystem(); /* Clear Region defined by (1,1) as the upper right hand corner and (10,10) as the lower right hand corner */ ClearRegion(1,1,10,10,CREATE_VIDEO_ATTRIBUTE(black,white)); } There is no return value for ClearRegion(). Page 283 The C Window Library Page 283 SCROLLING SCREENS ----------------- These functions scroll portions of the screen up or down. ScrollScreenUp() ---------------- The ScrollScreenUp() function scrolls a rectangular portion of the screen up a specified number of lines. Here is the prototype: void ScrollScreenUp(int numlines, int urow, int ucol, int lrow, int lcol, int attr) The first argument is the number of lines to scroll the region. The second and third arguments are the (row,col) coordinates of the upper left hand corner of the rectangular region to scroll. The fourth and fifth arguments are the (row,col) of the lower right hand corner of the rectangular region. The last argument is the attribute to use for blank lines created when the region is scrolled. Example: #include "window.h" main() { WindowInitializeSystem(); ScrollScreenUp(1,1,3,5,10, CREATE_VIDEO_ATTRIBUTE(black,white)); } There is no return value for ScrollScreenUp(). ScrollScreenDown() ------------------ The ScrollScreenDown() function scrolls a rectangular portion of the screen down a specified number of lines. Here is the prototype: void ScrollScreenDown(int numlines, int urow, int ucol, int lrow, int lcol, int attr) The first argument is the number of lines to scroll the region. The second and third arguments are the (row,col) coordinates of the upper left hand corner of the rectangular region to scroll. The fourth and fifth arguments are the Page 284 The C Window Library Page 284 (row,col) of the lower right hand corner of the rectangular region. The last argument is the attribute to use for blank lines created when the region is scrolled. Example: #include "window.h" main() { WindowInitializeSystem(); ScrollScreenDown(1,1,3,5,10, CREATE_VIDEO_ATTRIBUTE(black,white)); } There is no return value for ScrollScreenDown(). Page 285 The C Window Library Page 285 CHANGING THE VIDEO MODE ----------------------- With The C Window Library, you can change the video mode at any time. The video mode determines the width of the screen, and whether the screen is in text or graphics mode. SetVideoMode() -------------- The SetVideoMode() function changes the video mode. Here is a prototype: void SetVideoMode(int modenum) The only argument is the mode number. Refer to the Video Paging section on page 5 for more information on mode numbers and what they display. When the video mode is changed, the screen is cleared. This cannot be prevented. You must redisplay any windows that were on the screen. If the change of video mode results in a change in screen dimensions, then you must read the following sections on CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE SCREEN. Even though The C Window Library does not support graphics mode, you can change to graphics mode in The C Window Library, Example: #include "window.h" main() { WindowInitializeSystem(); SetVideoMode(3); /* Change to video mode 3 */ } There is no return value for SetVideoMode(). Page 286 The C Window Library Page 286 CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE SCREEN ----------------------------------------------------- Changing rows ------------- With The C Window Library, you can change the number of rows on the video screen. However, there are some things to watch out for when changing the number of rows, especially if you have windows displayed on the screen. If you are not using any window related functions, you can change the number of displayable rows safely by doing two things: a) Call the SetVideoRows() function to change the number of rows. b) Call AdjustGlobalData() to adjust the global variables used by The C Window Library that keep track of the screen dimensions. If you are going to create or have created windows you must do three things: a) Make sure that any window defined will have valid coordinates when the number of rows are changed. There may be cases where a window occupies a row that exists in one screen mode, but the row does not exist in another screen mode. If there are windows that will have invalid coordinates in another screen configuration, you must resize them, remove them, or whatever it takes to resolve the invalid coordinates. b) Call the SetVideoRows() function. c) Call the AdjustScreenInfo() function. This function adjusts all global variables defined in The C Window Library to reflect the new number of rows. Whether there are or are not windows defined, the visible video page MUST be page 0 before changing the number of screen rows. AdjustScreenInfo() ------------------ This function must be called after SetVideoRows() is called if you are going to, or have initialized and/or displayed windows. Here is the prototype: int AdjustScreenInfo(int page) Page 287 The C Window Library Page 287 The only argument is the video page to adjust to the new screen height. Because of the new dimension of the screen, there has to be a reshuffling of a few global arrays, constants, variables, etc. The AdjustScreenInfo() function does just this. If you do not call AdjustScreenInfo(), you may see problems if you try to manipulate windows on the new screen. See SetVideoRows() for an example of AdjustScreenInfo(). If there are no errors, AdjustScreenInfo() returns NO_ERROR. If there are errors, AdjustScreenInfo() returns the following value: NO_HEAP_MEM if there is not enough memory to allocate for the global arrays, structures, etc. AdjustGlobalData() ------------------ The AdjustGlobalData() function should be called after you have changed the number of video rows using SetVideoRows() (defined below). This resets the global variables necessary for non-window functions to execute properly. Here is the prototype: void AdjustGlobalData(void) There are no arguments and no return value for AdjustGlobalData(). If you have called AdjustScreenInfo(), you do not have to call AdjustGlobalData(). See below for an example of AdjustGlobalData(). SetVideoRows() -------------- The SetVideoRows() function changes the number of video rows on the screen. Here is a list of video adapters and there row number capabilities: Page 288 The C Window Library Page 288 Video Type Number of Rows Possible ---------- -------------- CGA, MDA, Hercules 25 EGA 25, 43 MCGA 25, 50 VGA 12, 14, 21, 25, 28, 43, 50 The list above are the values SetVideoRows() uses, depending on the adapter that The C Window Library has detected. If your video card supports a row configuration that is not supported by the SetVideoRows() function, consult the 'Changing columns' section and proceed as if you are changing the number of columns. Here is the prototype for SetVideoRows(): int SetVideoRows(int numrows, int modeflag) The first argument is the number of screen rows. The modeflag tells whether the video mode should be reset. If modeflag is 0, the video mode is not reset. Any other value for modeflag will cause a video mode reset. This reset may or may not be necessary, so experiment with both values for modeflag. Example: #include "window.h" main() { WindowInitializeSystem(); ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white)); VideoWriteString( "Press a key to change to a new video mode",1,1); GET_KEY(); if (VGA_MODE_ON || MCGA_MODE_ON) SetVideoRows(50,0); else if (EGA_MODE_ON) SetVideoRows(43,0); else { VideoWriteString( "Hardware does not support changing video rows",2,1); exit(0); } AdjustGlobalData(); VideoWriteString( "Press a key again to change to 25 lines",2,1); Page 289 The C Window Library Page 289 GET_KEY(); SetVideoRows(25,0); AdjustGlobalData(); } The example above uses the constants VGA_MODE_ON, MCGA_MODE_ON, and EGA_MODE_ON. These constants are discussed in the VIDEO MACROS section. Here is another example, but now we have a window on the screen. Example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); WindowOpen(w); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Press a key to change rows",1,1); GET_KEY(); if (VGA_MODE_ON || MCGA_MODE_ON) SetVideoRows(50,0); else if (EGA_MODE_ON) SetVideoRows(43,0); else { WindowWriteString(w,"Cannot change rows",1,1); exit(0); } /* Adjust the screen information */ AdjustScreenInfo(0); /* OK to adjust to new height */ WindowResizeHeight(w,40,ANCHORTOP); WindowWriteString(w,"Now press a key to change back",2,1); GET_KEY(); /* First we must resize window */ WindowResizeHeight(w,10,ANCHORTOP); SetVideoRows(25,0); Page 290 The C Window Library Page 290 AdjustScreenInfo(0); } Note the use of AdjustScreenInfo() after a reset is made. If there are no errors, SetVideoRows() returns no errors. If there are errors SetVideoRows() returns the following value: INVALID_ROWS if the number of rows is not supported for the detected monitor type. Changing columns ---------------- The number of columns can be changed, but there are two things to watch out for. First, to change from 40 column mode to 80 column mode or vice-versa, is a matter of changing the video mode. Changing the video mode from 40 to 80 column mode or from 80 to 40 requires a BIOS function that is present on all systems that support 40 column mode. 40 column and 80 column modes ----------------------------- To change to 40 column mode do the following: SetVideoMode(0); /* this changes to 40 column black and white mode */ or SetVideoMode(1); /* this changes to 40 column color mode */ The example above only works if you have a CGA, EGA, MCGA, or VGA card. To change to 80 column mode do the following: SetVideoMode(2); /* this changes to Black and White 80 column mode */ or SetVideoMode(3); /* use this for color 80 column mode */ or Page 291 The C Window Library Page 291 SetVideoMode(7); /* use this for mono cards */ SetVideoMode(7) works for all adapters, while SetVideoMode(2) and SetVideoMode(3) works only for CGA, EGA, MCGA, or VGA cards. Modes higher than 80 columns ---------------------------- There are video systems that support video modes greater than 80 columns. The problem is that for each different brand of video adapter, there is a unique way of changing to a higher column mode. Most of these adapters support an additional BIOS function that must be called to change to any screen column mode higher than 80. Therefore, it is up to you (the programmer) to find out how to change the video system from 80 columns to a higher column mode. Once you are familiar with how to do this, changing the number of columns is almost the same as changing the number of rows. If you are using any window related functions, you can change the number of displayable columns safely by doing three things: a) Call the appropriate routine to change the number of columns. If this is a call to SetVideoMode(), the screen will be cleared. b) Call AdjustScreenInfo() to adjust the global variables used by The C Window Library that keep track of the screen dimensions. c) Readjust and/or redraw any windows on the screen. Make sure that all windows fit on the screen, whether they are hidden or not. If you are not using any windows in your application, replace the call to AdjustScreenInfo() in step b) with a call to AdjustGlobalData(). This example works for the ATI VGA card. This changes the mode to 132 columns: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) WPOINTER w; main() { WindowInitializeSystem(); WindowSaveInitial(0); w = WindowInitialize(BORDER,1,1,30,10,NORM,NORM,SINGLEBOX); WindowOpen(w); Page 292 The C Window Library Page 292 WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Press a key to change columns",1,1); GET_KEY(); /* Set Video Mode to 132 columns x 25 rows (Works for ATI VGA card) */ SetVideoMode(0x23); /* Adjust the screen information and redisplay window */ AdjustScreenInfo(0); WindowDisplay(w,1,NOEFFECT); /* OK to adjust to new height */ WindowResizeWidth(w,100,ANCHORLEFT); WindowWriteString(w,"Now press a key to change back",2,1); GET_KEY(); /* First we must resize window */ WindowResizeWidth(w,30,ANCHORLEFT); /* Set back to 80 column mode */ SetVideoMode(3); AdjustScreenInfo(0); WindowDisplay(w,1,NOEFFECT); } Page 293 The C Window Library Page 293 CURSOR MANIPULATION ------------------- The functions defined in this section manipulate the cursor. The following functions can be called without calling WindowInitializeSystem(). MoveCursor() ------------ This function moves the cursor to a different location. Here is the prototype: void MoveCursor(int row, int col, int page) The first two arguments are the row and column positions of where to move the cursor. The last argument is the video page of the cursor you want to move. Example: #include "window.h" main() { MoveCursor(1,5,0); /* Move cursor to row 1 column 5 on video page 0 */ } There is no return value for MoveCursor(). ChangeCursor() -------------- The ChangeCursor() function changes the shape of the cursor. The shape of the cursor is determined by its starting and ending scan lines. Here is a prototype: void ChangeCursor(unsigned startline, unsigned endline) The first argument is the starting scan line and the second argument is the ending scan line. For monochrome systems, there are 12 scan lines numbered 0 thru 11, while on color systems there are 8 scan lines numbered 0 thru 7. The starting scan line is the top line of the cursor, and the ending scan line is the last line of the cursor. There is no check to see if the starting scan line and the ending scan lines are valid. Page 294 The C Window Library Page 294 Example: #include "window.h" main() { WindowInitializeSystem(); ChangeCursor(6,7); /* This is an underline cursor */ GET_KEY(); ChangeCursor(0,7); /* This is a thick cursor */ } There is no return for ChangeCursor(). GetCursorShape() ---------------- This function returns the shape of the cursor in scan lines. Here is the prototype: void GetCursorShape(unsigned *startline, unsigned *endline) When this function returns, the staring scan line is placed in the integer pointed to by scanline, and the ending scan line is placed in the integer pointed to by endline. Example: #include "window.h" main() { int start, end; WindowInitializeSystem(); GetCursorShape(&start, &end); VideoPrintf("\nThe starting scan line is %d\n" "The ending scan line is %d", start,end); } There is no return value for GetCursorShape(). GetCursorPosition() ------------------- This function gets the current cursor position. Here is the prototype: void GetCursorPosition(int *row, int *col, int page) The first argument is a pointer to an integer that will be Page 295 The C Window Library Page 295 set to the current row. The second argument is a pointer to an integer that will be set to the current column. The last argument is the video page of the cursor. Example: #include "window.h" main() { int row,col; MoveCursor(10,15); GetCursorPosition(&row,&col,0); WindowInitializeSystem(); VideoPrintf("\nThe row of the cursor is %d\n" "The column is %d", row,col); } There is no return value for GetCursorPosition(). The following functions serve as shortcuts in changing the cursor shape. HideCursor() ------------ Hides the cursor on the screen. Here is the prototype: void HideCursor(void) BlockCursor() ------------- Displays the cursor as a thick block. void BlockCursor(void) ThinCursor() ------------ Displays the cursor as an underline cursor. void ThinCursor(void) Page 296 The C Window Library Page 296 Example: #include "window.h" main() { WindowInitializeSystem(); MoveCursor(1,1,0); VideoWriterString("Press a key to hide the cursor",1,1); GET_KEY(); HideCursor(); VideoWriterString( "Press a key to change cursor to a block",2,1); GET_KEY(); BlockCursor(); VideoWriterString( "Press a key to change cursor to a thin cursor",3,1); GET_KEY(); ThinCursor(); } There are no return values for HideCursor(), BlockCursor(), or ThinCursor(). Page 297 The C Window Library Page 297 GETTING VIDEO INFORMATION ------------------------- You can get information about the video configuration by calling the GetVideoBiosInfo() function. VIDEO_CONFIG structure ---------------------- To get information about the video configuration, you must pass a pointer to a VIDEO_CONFIG structure. This structure is defined as follows: typedef struct { unsigned int video_mode; /* Current video mode */ unsigned int cursor_startline; /* Starting scan line of cursor */ unsigned int cursor_endline; /* Ending scan line of cursor */ unsigned int cursor_row; /* Screen row of cursor */ unsigned int cursor_col; /* Column of cursor */ unsigned int video_page; /* Current visible video page */ unsigned int video_pagesize; /* Size in bytes of the video page */ unsigned int video_rows; /* Number of displayable rows */ unsigned int video_cols; /* Number of displayable columns * / unsigned int char_height; /* Height (in scan lines) of a character */ unsigned int crt_port_address; /* Address of CRT status port */ unsigned int crt_mode_setting; /* Current CRT Mode Setting */ unsigned int crt_color_setting; /* Current CRT color settings */ } VIDEO_CONFIG; GetVideoBiosInfo() ------------------ This function returns information about the current video configuration. Here is the prototype: void GetVideoBiosInfo(VIDEO_CONFIG *v) The only argument is a pointer to a VIDEO_CONFIG structure. This structure is filled in with the appropriate values. Page 298 The C Window Library Page 298 Example: #include "window.h" VIDEO_CONFIG v; main() { WindowInitializeSystem(); /* Get video information */ ClearScreen(CREATE_VIDEO_ATTRIBUTE(black,white)); GetVideoBiosInfo(&v); VideoPrintf("The video mode is %d\n" "The starting scan line of the cursor is %d\n" "The ending scan line of the cursor is %d \n" "The row of the cursor is %d \n" "The column of the cursor is %d\n" "The video page is %d\n" "The size of the video page is %d\n" "The number of rows is %d\n" "The number of columns is %d\n" "The height of the characters is %d\n", v.video_mode, v.cursor_startline, v.cursor_endline, v.cursor_row,v.cursor_col, v.video_page, v.video_pagesize, v.video_rows, v.video_cols, v.char_height); } There is no return value for GetVideoBiosInfo(). Page 299 The C Window Library Page 299 TIMED DELAYS ------------ One of the problems that has been addressed in The C Window Library is the lack of a delay() function in most C compiler packages. The delay() function delays program execution for a certain number of milliseconds. Borland's Turbo C compiler is one of the few that has a delay() function. The other compilers may have a sleep() function, but usually these functions do not have millisecond accuracy. One of the problems was to write a delay() function that would work for all the major C compilers, work with millisecond accuracy, work for any speed PC, and last but not least, without using floating point arithmetic. This function was written in assembly language for accuracy. The use of the delay() is used extensively in displaying and hiding windows with certain special effects. delay() ------- The delay() function delays the program for a certain number of milliseconds. Here is the prototype: void delay(unsigned millisecs) The only argument is the number of milliseconds to delay. If you are using the Turbo C version of The C Window Library, this function is already included in the Turbo C library. However, if you are using another compiler you now have a delay() function! Example: main() { WindowInitializeSystem(); delay(50); /* Delay for 50 milliseconds */ } You must call WindowInitializeSystem() before using delay(). There is no return value for delay(). Page 300 The C Window Library Page 300 SOUND FUNCTIONS --------------- The C Window Library also supports sound functions for compilers that are lacking these functions. sound() and nosound() --------------------- The sound() function sounds a tone with a specified frequency in Hertz (cycles per second). Here is a prototype: void sound(unsigned frequency) The nosound() function turns off the tone generated by the sound() function. Example: #include "window.h" main() { unsigned i; WindowInitializeSystem(); for (i=100;i<=1000;i++) sound(i); for(i=1000;i>=100;i--) sound(i); nosound(); } Note for Turbo users: You should include "dos.h" in your files that contain sound() and nosound(). All other compilers should include "window.h". Note for Power C users: If you are using the Power C compiler, you must include "window.h" or any file that includes window.h after bios.h. This is to ensure that the linker does not get confused with the Power C function called sound(), which works differently than the sound() function defined above. MakeSound() ----------- The MakeSound() function sounds a tone for a duration of time. Here is the prototype: Page 301 The C Window Library Page 301 void MakeSound(unsigned freq, unsigned millisec) where freq, is the frequency of the tone (in Hertz) and millisec is the number of milliseconds to sound the tone. Example: -------- #include "window.h" main() { WindowInitializeSystem(); /* Produce a 440 Hertz tone for 3 seconds */ MakeSound(440,3000); } There is no error return for this function. Page 302 The C Window Library Page 302 ERROR HANDLING -------------- Whenever an error has occurred in The C Window Library, a user defined error function can be called. The window_error_func function pointer -------------------------------------- The window_error_func function pointer can point to an error function that is performed whenever there is an error encountered in one of The C Window Library functions. If the global variable check_existence_flag is set to 1 and there is an error, The C Window Library will automatically call window_error_func. Here is the prototype: void (*window_error_func)(int errcode, char *sourcefile, int sourceline, char *funcname) The errcode is one of the defined error codes included in The C Window Library. Refer to page 6 of the main documentation for more information of the error codes and their definitions. The second argument is the name of the file where the error occurred. Only users with the source code to The C Window Library will have access to this file. The third argument is the offending line in the source file of where the error occurred. The last argument is the name of the function of where the error occurred. By default window_error_func points to a void null function (VOIDNULLFN), therefore no error function is called. Here is an example of how to implement automatic error checking: #include "window.h" #define WHITEONRED CREATE_VIDEO_ATTRIBUTE(red,white) void custom_error_func(int, char *, int, char *); WPOINTER w, error_window; void initialize_error(); main() { WindowInitializeSystem(); WindowSaveInitial(0); window_error_func = custom_error_func; /* Assign error function */ initialize_error(); WindowOpen(w); /* will be flagged for an error */ } void initialize_error() /* Initialize error window and error handler */ Page 303 The C Window Library Page 303 { error_window = WindowInitialize(BORDER,1,1,60,5,WHITEONRED, WHITEONRED,SINGLEBOX); WindowOpen(error_window); } void custom_error_func(int errcode, char *sourcefile, int sourceline, char *funcname) { int ch; MakeSound(100,500); /* Produce an error beep */ if (errcode == NO_HEAP_MEM) /* Always check for the heap memory error separately */ { VideoWriteString("You have ran out of Heap Memory",1,1); VideoWriteString( "Press 'Q' to quit program, Any other key to Continue...", 2,1); } else /* Display error window */ { WindowClear(error_window); WindowDisplay(error_window,1,EXPLODE); WindowPrintf(error_window, "Error Code: %d\nSource File: %s\nSource Line %d\n" "Error Occurred in %s", errcode,sourcefile,sourceline,funcname); WindowWriteString(error_window, "Press 'Q' to quit program, Any other key to Continue...", 5,1); } ch = GET_KEY(); if (ch == 'Q' || ch == 'q') exit(0); else if (errcode != NO_HEAP_MEM) WindowHide(error_window,CONTRACT); } The above example initializes an error window and sets the window_error_func function pointer to point to the function custom_error_func(). Whenever an error occurs in The C Window Library, custom_error_func() will be called. Please note the check to see if the NO_HEAP_MEM error has occurred. It is important that you check for this error condition separately. The reason for this is that if there is not enough heap memory, you may inadvertently call a function in your error handler that calls on malloc() or any Page 304 The C Window Library Page 304 of the other memory allocation related functions. This will either freeze your system, or more peculiarly, cause your error handler to be called in an infinite loop because of the repeated failing calls to malloc() or its related functions. In the latter case, you will run out of stack space. If you want to unassign the window_error_code function pointer, use the following line in your code: window_error_func = VOIDNULLFN; Page 305 The C Window Library Page 305 USING A MOUSE WITH THE C WINDOW LIBRARY --------------------------------------- With The C Window Library, you can create applications that use a Microsoft compatible mouse to select from popup, pulldown, and bar menus as well as getting mouse presses. Using the mouse for menus will be discussed in this section, while getting and testing for button presses will be discussed in the KEYBOARD MACROS section below. Installing the Mouse Library ---------------------------- Before using the mouse library, make sure that you read the README file concerning installing the mouse library. Include files ------------- The only include file needed is cwlmouse.h. This file also includes window.h. Initializing the Mouse with MouseInitializeSystem() --------------------------------------------------- Before you can use a mouse, you must initialize it by calling MouseInitializeSystem(). This function tests for a Microsoft compatible mouse and returns a value denoting whether a mouse is found. Here is the prototype: int MouseInitializeSystem(int intype, int *button, int hpos, int vpos) The first argument informs MouseInitializeSystem() to whether you just want to test to see if a mouse is installed and not to activate the mouse, or to not only test for the mouse, but to activate it. If the first argument is MOUSE_TEST, MouseInitializeSystem() will just return an integer denoting whether a mouse is found. If the first argument is MOUSE_FULL_INSTALL, not only is a status returned, but the mouse will be activated. The second argument is a pointer to an integer that will contain the number of buttons that the mouse has. This number will usually be 2 or 3. The third and fourth arguments are the screen coordinates of where to place the mouse cursor on the screen. The third argument is the row, and the fourth argument is the column to place the mouse cursor. MouseInitializeSystem() returns NOMOUSE if a mouse is not installed, or MOUSEFOUND if a mouse is installed. Page 306 The C Window Library Page 306 MouseInitializeSystem() must be called after calling WindowInitializeSystem() for it to work properly. Turning off the mouse with MouseRestoreSystem() ----------------------------------------------- Before terminating a program that has called MouseInitializeSystem() you should call MouseRestoreSystem(). If you do not call MouseRestoreSystem(), the mouse will still be 'alive', even though the application has terminated. Here is the prototype: int MouseRestoreSystem(void) If the mouse was not initialized previously with MouseInitializeSystem(), MouseRestoreSystem() returns NOMOUSE, otherwise the return value is NO_ERROR. Example: #include "cwlmouse.h" main() { /* initialize mouse */ MouseInitializeSystem(); /* ... */ /* turn off mouse */ MouseRestoreSystem(); } If you want to turn the mouse back on after calling MouseRestoreSystem(), you must call MouseInitializeSystem() again. Example: #include "cwlmouse.h" main() { int button; int ismouse; WindowInitializeSystem(); ismouse = (MouseInitializeSystem(MOUSE_FULL_INSTALL, &button,1,1) == MOUSEFOUND)); MoveCursor(1,1,0); if (ismouse) Page 307 The C Window Library Page 307 VideoPrintf( "Mouse was found. Number of buttons is %d\n",button); else VideoPrintf("Mouse not found"); } Using a mouse with popup menus ------------------------------ Once the mouse is initialized, you can use the mouse to make selections with popup menus. To move the highlight bar with the mouse, position the mouse cursor over any menu entry in the window, and hold the left mouse button down. If the mouse is moved while holding the left button down, the highlight is moved along with the mouse cursor. A selection is made by releasing the left mouse button while the mouse cursor is on an active menu entry. You can also scroll through the menu entries by placing the mouse on either a down arrow or up arrow symbols on the popup menu window, and then holding the left mouse button down. By default, the symbols appear at the bottom border of the window. If the popup window is borderless, the POPUPMOUSESCROLL option is ignored. To activate the mouse so that it can be used for popup menus, you must set the popup option POPUPMOUSE on. If you also want to use the scroll through option described above, POPUPMOUSESCROLL should also be turned on. Example: #include "menu.h" #include "cwlmouse.h" int menu_func(); POPUP_MENU_ENTRY menu_items[] = { " Load F3",1,'L',F3,menu_func, " Pick Alt-F3",2,'P',ALTF3,menu_func, " New" ,3,'N',0,menu_func, " Save F2",4,'S',F2,menu_func, " Write to ",5,'W',0,menu_func, " Directory ",6,'D',0,menu_func, " Change Dir" ,7,'C',0,menu_func, " OS shell" ,8,'O',0,menu_func, " Quit Alt-X" ,9,'Q',ALTX,menu_func, CWL_NULL,0}; unsigned int menu_colors[5]; POPUP_MENU_PTR p; Page 308 The C Window Library Page 308 main() { int b; WindowInitializeSystem(); WindowSaveInitial(0); /* Remember to save the initial screen */ MouseInitiailizeSystem(MOUSE_FULL_INSTALL,&b,1,1); /* define colors */ menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,blue); menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(cyan,black); menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); /* create a POPUP_MENU_PTR */ p = PopupCreateMenu(menu_items,menu_colors, 1,1,6, POPUPSTATIC | POPUPMOUSE | POPUPMOUSESCROLL, WNULLFN,VWNULLFN); PopupSelectMenu(p, /* POPUP_MENU_PTR */ 1, /* rank of popup window */ 1 /* menu entry to start on */ ); MouseRestoreSystem(); } int menu_func(POPUP_MENU_PTR p, unsigned which) { WPOINTER w; w = WindowInitialize(BORDER,15,15,40,4, CREATE_VIDEO_ATTRIBUTE(black,white), CREATE_VIDEO_ATTRIBUTE(black,white), SINGLEBOX); WindowOpen(w); WindowClear(w); WindowPrintf(w,"You have selected %s", POPUP_ENTRY_STRING(p,which)); WindowWriteCenterString(w,"Press a key to continue",3); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowFree(w,NOEFFECT); if (which == 9) return POPUP_EXIT; else return POPUP_CONTINUE; } Page 309 The C Window Library Page 309 The above example uses the popup menu option POPUPMOUSE and POPUPMOUSESCROLL options in the PopupCreateMenu() function. Also note the call to MouseInitializeSystem() to initialize the mouse system. You must use the constant MOUSE_FULL_INSTALL in the MouseInitializeSystem() function to make sure that the POPUPMOUSE and the POPUPMOUSESCROLL options will take effect. If a mouse does not exist, or the mouse is not activated, POPUPMOUSE and POPUPMOUSESCROLL will be ignored. Also note that the include file cwlmouse.h was included. These are the only changes needed for mouse support for the popup menus. Popup Menu's pre-function for mouse ----------------------------------- When the POPUPMOUSESCROLL option is used for popup menus, the menu can be scrolled automatically by placing the mouse on either the up or down scroll characters on the popup window, and pressing the left mouse button. The normal pre-function for the popup menu, namely the function pointed to by global_popup_prefunc, is disabled if you use the mouse to scroll through the entries in the manner described above. If you want to perform a function when the menu bar is moved automatically from choice to choice, you should use the popup_mouse_move_func function pointer. Here is the prototype: void (*popup_mouse_move_func)(POPUP_MENU_PTR p, unsigned current) p is the current popup menu, and current is the current selection that the highlight bar is on. Note the difference in the second argument. The global_popup_prefunc function pointer has a pointer to an integer as the second argument, while the popup_mouse_move_func has an integer as the second argument. Also note that the popup_mouse_move_func returns nothing, while the global_popup_prefunc returns a value back to the menu manager. If you use the mouse the 'normal' way (pointing the mouse to the actual menu entry and moving the mouse up or down while holding the left mouse button down), the normal pre-function is not disabled. The reason for having the popup_mouse_move_func function pointer is that there may be a description displayed for each menu entry, where the displaying of the menu entry is done by the function pointed to by global_popup_prefunc. Here is a small example: Page 310 The C Window Library Page 310 #include "menu.h" #include "cwlmouse.h" int display_choice(); void do_display_choice(); POPUP_MENU_PTR p; /* other initializations */ main() { WindowInitializeSystem(); WindowSaveInitial(); MouseInitializeSystem(MOUSE_FULL_INSTALL,&b,1,1); p = PopupCreateMenu(/* arguments */); PopupSetOptions(p,POPUPMOUSE|POPUPMOUSESCROLL,1); global_popup_prefunc = display_choice; popup_move_mouse_func = do_display_choice; /* ... */ } display_choice(POPUP_MENU_PTR p, int *choice) { /* display info for entry in a window */ return POPUP_CONTINUE; } void do_display_choice(POPUP_MENU_PTR p, int choice) { display_choice(p,&choice); } Using a mouse with bar menus ---------------------------- To move the highlight bar with the mouse, position the mouse cursor over any menu entry in the window, and hold the left mouse button down. If the mouse is moved while holding the left button down, the highlight is moved along with the mouse cursor. A selection is made by releasing the left mouse button while the mouse cursor is on an active menu entry. To activate the mouse so that it can be used for bar menus, you must set the bar menu option BARMOUSE on. Page 311 The C Window Library Page 311 Example: #include "menu.h" #include "cwlmouse.h" int menu_func(); BAR_MENU_ENTRY bar_items[] = { "File",1,4,'F',ALTF,menu_func, "Edit",1,10,'E',0,menu_func, "Run",1,17,'R',0,menu_func, "Compile",1,23,'C',0,menu_func, "Project",1,33,'P',0,menu_func, "Options", 1,43,'O',0,menu_func, "Debug",1,53,'D',0,menu_func, "Break/watch",1,61,'B',0,menu_func, CWL_NULL}; unsigned int menu_colors[5]; BAR_MENU_PTR b; main() { int b; WindowInitializeSystem(); WindowSaveInitial(0); MouseInitializeSystem(MOUSE_FULL_INSTALL,&b,1,1); menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,blue); menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(cyan,black); menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(white,black); /* create a BAR_MENU_PTR */ b = BarCreateMenu(bar_items,menu_colors, 1,1, BARSTATIC | BARWRAP | BARMOUSE,WNULLFN); BarSelectMenu(b,1,1); MouseRestoreSystem(); } Page 312 The C Window Library Page 312 int menu_func(BAR_MENU_PTR b, unsigned which) { WPOINTER w; w = WindowInitialize(BORDER,15,15,40,4, CREATE_VIDEO_ATTRIBUTE(black,white), CREATE_VIDEO_ATTRIBUTE(black,white), SINGLEBOX); WindowOpen(w); WindowPrintf(w,"You have selected %s", BAR_ENTRY_STRING(b,which)); WindowWriteCenterString(w,"Press a key to continue",3); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowFree(w,NOEFFECT); if (which == 9) return BAR_EXIT; else return BAR_CONTINUE; } The above example uses the bar menu option BARMOUSE option in the BarCreateMenu() function. Also note the call to MouseInitializeSystem() to initialize the mouse system. You must use the constant MOUSE_FULL_INSTALL in the MouseInitializeSystem() function to make sure that the BARMOUSE option will take effect. If a mouse does not exist, or the mouse is not activated, BARMOUSE will be ignored. Also note that the include file cwlmouse.h was included. These are the only changes needed for mouse support for the bar menus. Using a mouse with pulldown menus --------------------------------- If the menu options for the mouse are turned on for all popup menus and the bar menu, and these menus are used as part of a pulldown menu system, the mouse behaves exactly the same except for the following differences: a) Holding the left mouse button down and positioning the mouse cursor over a bar menu entry will bring up the popup menu that is associated with the bar entry. If there is no popup menu defined for a particular bar entry, releasing the mouse button will invoke the entry's function. b) Releasing the mouse button when it is positioned over a bar entry, and the bar entry has a popup associated with it, does nothing. A general rule is that a menu function is only executed when the highlight bar is positioned on a menu entry that has a function associated with it. Page 313 The C Window Library Page 313 Changing the mouse defaults --------------------------- By default, the left mouse button is held down when moving the highlight bar. If you prefer a different button to be used to move the highlight bar, you can change the button by changing the following global variables: int popmenu_button_press - holds the current button to be used to move the highlight bar in popup menus. int barmenu_button_press - holds the current button to be used to move the highlight bar in bar menus. The following constants can be assigned to these two global variables: Constant Definition -------- ---------- MOUSELEFT_PRESS Left button. MOUSERIGHT_PRESS Right button. MOUSEMIDDLE_PRESS Middle button. By default, popmenu_button_press and barmenu_button_press are assigned MOUSELEFT_PRESS. Here is an example of changing these variables: #include "cwlmouse.h" #include "menu.h" main() { ... MouseInitializeSystem( /* arguments */ ); /* change mouse menu buttons */ popmenu_button_press = MOUSERIGHT_PRESS; barmenu_button_press = MOUSERIGHT_PRESS; ... } The popmenu_button_press and barmenu_button_press variables are assigned their default values when MouseInitializeSystem() is called. If you want to change these variables, make sure that the change is made after calling MouseInitializeSystem(). Page 314 The C Window Library Page 314 WINDOW AND VIRTUAL WINDOW MACROS -------------------------------- Note : These macros should be used after making a call to WindowInitializeSystem() or else unpredictable values will be returned. The following macros are defined in the window.h file. The window w is NOT CHECKED for validity. ISBORDER(w) - Returns 1 if window has a border, 0 otherwise. ISWRAP(w) - Returns 1 if window wrap is on, 0 otherwise. ISOPEN(w) - Returns 1 if window has been opened for read/write, 0 otherwise. ISVISIBLE(w) - Returns 1 if window is visible, 0 otherwise. ISVIEWPORT(w) - Returns 1 if window is a viewport, 0 otherwise. ISWINDOW(vw) - Returns 1 if virtual window has any viewports, 0 otherwise. ISBUFSAVE(w) - Returns 1 if text buffer for window was successfully, allocated, 0 otherwise. ISSEETHRU(w) - Returns 1 if window is in see-thru mode, 0 otherwise. ISFROZEN(w) - Returns 1 if window is frozen from doing screen updates when the virtual window has changed, 0 otherwise. ISSHADOW(w) - Returns 1 if the window has a shadow, 0 otherwise. ISSHADOWTRANS(w) - Returns 1 if the shadow is transparent, 0 otherwise. SHADOW_POS(w) - Returns the position of the shadow as an integer. The valid positions are as follows: Shadow Position Return Value --------------- ------------ SHADOWUPLEFT 1 SHADOWUPRIGHT 2 SHADOWLOWLEFT 3 Page 315 The C Window Library Page 315 SHADOWLOWRIGHT 4 If there is no shadow, a 0 is returned. SHADOW_CHAR(w) - Returns the current character used to draw the window's shadow. Return value is undefined if the window has no shadow. SHADOW_ATTR(w) - Returns the current video attribute used to draw the window's shadow. Return value is undefined if the window has no shadow SHADOW_WIDTH(w) - Returns the width of the window's shadow. Return value is undefined if the window has no shadow. SHADOW_HEIGHT(w) - Returns the height of the window's shadow. Return value is undefined if the window has no shadow. VIRTUAL_ATTRIBUTE_ON(vw) - Returns 1 if the virtual window vw is attributed, 0 otherwise. VIRTUAL_WINDOW_EXIST(vw) - Returns 1 if virtual window was initialized, 0 otherwise. VIRTUAL_HEIGHT(vw) - Returns the number of rows in a virtual window vw. VIRTUAL_WIDTH(vw) - Returns the number of columns in a virtual window. VIRTUAL_WINDOW(w) - Returns the virtual window that the viewport w is currently viewing. VIEWPORT_ROW(w) - Returns the upper left row of where the viewport w is positioned on the virtual window. VIEWPORT_COLUMN(w) - Returns the upper left column of where the viewport w is positioned on the virtual window. VIRTUAL_COORD_IN_VIEWPORT(w,row,col) - Returns 1 if the virtual window coordinates (row,col) are inside the viewport w, 0 otherwise. The virtual window must have w as a viewport. WINDOW_BORDER_CHARS(w) - Returns the current border of a window as a string. Page 316 The C Window Library Page 316 WINDOW_BORDER_COLOR(w) - Returns the border color of the window w. WINDOW_COLUMN(w) - Returns the absolute column of the upper left hand corner of the window. WINDOW_EXIST(w) - Returns 1 if window was initialized, 0 otherwise. WINDOW_HEIGHT(w) - Returns the height of the text area of the window w. WINDOW_PAGENUM(w) - Returns the video page of where the window will be displayed. WINDOW_RANK(w) - Returns the rank of the window w. WINDOW_ROW(w) - Returns the absolute row coordinate of the upper left hand corner of the window w. Page 317 The C Window Library Page 317 MENU MACROS ----------- The following macros are defined in the header file menu.h. Popup Menu Macros ----------------- POPUP_CONFIRM_ON(p) - Returns 1 if the POPUP_MENU_PTR p has the confirmation for hotkey selections on, 0 otherwise. POPUP_DISPLAY_ON(p) - Returns 1 if the POPUP_MENU_PTR p's window is to be displayed regardless if the menu manager has returned to the calling function, 0 otherwise. POPUP_ENHANCED_ON(p) - Returns 1 if the popup menu will recognize enhanced keys, 0 otherwise. POPUP_ENTRY_STRING(p,entry) - Returns the entry string of POPUP_MENU_ENTRY entry. POPUP_EXPLODE(p) - Returns the special effect constant of the POPUP_MENU_PTR p. This special effect is used to hide, close, and open the popup menu's window. POPUP_MOUSE_ON(p) - Returns 1 if a mouse can be used to make selections, 0 otherwise. POPUP_MOUSE_SCROLL_ON(p) - Returns 1 if a mouse can be used to scroll through the entries if the entries cannot fit in the popup window, 0 otherwise. POPUP_NUMBER_OF_ENTRIES(p) - Returns the total number of entries defined in the POPUP_MENU_PTR p. POPUP_OVERRIDE_ON(p) - Returns 1 if POPUP_MENU_PTR p will have unavailable options processed, 0 otherwise. POPUP_PULLDOWN_ON(p) - Returns 1 if the POPUP_MENU_PTR p is incorporated in a pulldown menu system, 0 otherwise. POPUP_SCROLL_UP_CHAR(p) - This is the scroll up character that is displayed if the POPUPMOUSESCROLL option is on for the popup menu p. The default character is the up arrow. Page 318 The C Window Library Page 318 POPUP_SCROLL_DOWN_CHAR(p) - This is the scroll down character that is displayed if the POPUPMOUSESCROLL option is on for the popup menu p. The default character is the down arrow. POPUP_SCROLL_UP_ATTR(p) - This is the color attribute for the scroll up character that is displayed if the POPUPMOUSESCROLL option is on for the popup menu p. The default character is the attribute of the popup window. POPUP_SCROLL_DOWN_ATTR(p) - This is the color attribute for the scroll down character that is displayed if the POPUPMOUSESCROLL option is on for the popup menu p. The default character is the attribute of the popup window. POPUP_SCROLL_UP_ROW(p) - This is the row that the scroll up character is displayed in the popup window. The default is the bottom border of the window POPUP_SCROLL_UP_COLUMN(p) - This is the column that the scroll up character is displayed in the popup window. The default is column 1. POPUP_SCROLL_DOWN_ROW(p) - This is the row that the scroll down character is displayed in the popup window. The default is the bottom border of the window POPUP_SCROLL_DOWN_COLUMN(p) - This is the column that the scroll down character is displayed in the popup window. The default is column 1. POPUP_STATIC_ON(p) - Returns 1 if the POPUP_MENU_PTR p will remain on the screen when an entry is selected, 0 otherwise. POPUP_STRING_IN_WINDOW(p,entry) - Returns 1 if the POPUP_MENU_PTR p has entry number entry displayed in the popup menu's window, 0 otherwise. This macro is useful if you have a scrolling popup menu and want to know if a particular entry is displayed in the window. POPUP_VIRTUAL_WINDOW(p) - Returns the VWPOINTER of the popup menu. Page 319 The C Window Library Page 319 POPUP_WINDOW(p) - Returns the WPOINTER of the popup menu. POPUP_WRAP_ON(p) - Returns 1 if the highlight wrap of POPUP_MENU_PTR p is on, otherwise 0. Bar Menu Macros --------------- BAR_CONFIRM_ON(b) - Returns 1 if the BAR_MENU_PTR b has the confirmation for hotkey selections on, 0 otherwise. BAR_DISPLAY_ON(b) - Returns 1 if the BAR_MENU_PTR b's window is to be displayed regardless if the menu manager has returned to the calling function, 0 otherwise. BAR_ENHANCED_ON(b) - Returns 1 if the bar menu will recognize enhanced keys, 0 otherwise. BAR_ENTRY_AVAILABLE(b,entry) - Returns 1 if the BAR_MENU_ENTRY entry is available, 0 otherwise. BAR_ENTRY_STRING(b,entry) - Returns the entry string of BAR_MENU_ENTRY entry. BAR_EXPLODE(b) - Returns the special effect constant of the BAR_MENU_PTR b. This special effect is used to hide, close, and open the popup menu's window. BAR_NUMBER_OF_ENTRIES(b) - Returns the total number of entries defined in the BAR_MENU_PTR b. BAR_OVERRIDE_ON(b) - Returns 1 if BAR_MENU_PTR b will have unavailable options processed, 0 otherwise. BAR_PULLDOWN_ON(b) - Returns 1 if the BAR_MENU_PTR b is incorporated in a pulldown menu system, 0 otherwise. BAR_STATIC_ON(b) - Returns 1 if the BAR_MENU_PTR b will remain on the screen when an entry is selected, 0 otherwise. BAR_WINDOW(b) - Returns the WPOINTER of the bar menu. BAR_WRAP_ON(b) - Returns 1 if the highlight wrap of BAR_MENU_PTR b is on, otherwise 0. Page 320 The C Window Library Page 320 Pulldown Menu Macros -------------------- BAR_MENU_PTR_FROM_POPUP(pop) - Returns the BAR_MENU_PTR associated with the POPUP_MENU_PTR pop, which must be part of a pulldown menu system. BAR_MENU_PTR_FROM_PULLDOWN(pull) - Returns the BAR_MENU_PTR assocated with the PULLDOWN_MENU_PTR pull. POPUP_MENU_PTR_FROM_BAR(b,entry) - Returns the POPUP_MENU_PTR associated with the BAR_MENU_PTR b. The entry argument is the number of the POPUP_MENU_PTR desired in the pulldown menu system. For example, if you want to know the first POPUP_MENU_PTR given only a BAR_MENU_PTR, the call to this macro would be POPUP_MENU_PTR_FROM_BAR(b,1). POPUP_MENU_PTR_FROM_PULLDOWN(pull,entry) - Returns the POPUP_MENU_PTR associated with the PULLDOWN_MENU_PTR pull. The entry is the number of the desired POPUP_MENU_PTR desired in the pulldown menu system. PULLDOWN_MENU_PTR_FROM_BAR(b) - Returns the PULLDOWN_MENU_PTR associated with the bar menu b. PULLDOWN_MENU_PTR_FROM_POPUP(pop) - Returns the PULLDOWN_MENU_PTR associated with the POPUP_MENU_PTR pop. Page 321 The C Window Library Page 321 VIDEO MACROS ------------ The following macros are defined in the vidsys.h file. Note: by including window.h in your source files, vidsys.h is automatically included. CHECK_SNOW - Returns 1 if during direct screen writes that video "snow" is eliminated. You can also assign values to this macro. This macro is a pseudonym for the variable chksnow_. Example: #include "vidsys.h" ... int a; a = CHECK_SNOW; /* Returns 1 if snow checking on, 0 otherwise */ CHECK_SNOW = 0; /* Turn off snow checking */ CREATE_VIDEO_ATTRIBUTE(bg,fg) - creates a video attribute using bg as the background color, and fg as the foreground color. The following variables can be used: Variable Name Color Value ------- ----- ----- black Black 0 blue Blue 1 green Green 2 cyan Cyan 3 red Red 4 magenta Magenta 5 brown Brown 6 white White 7 gray Gray 8 lightblue Light Blue 9 lightgreen Light green 10 lightcyan Light cyan 11 lightred Light red 12 lightmagenta Light magenta 13 yellow Yellow 14 lightwhite Intense white 15 The variables above are initialized when WindowInitializeSystem() is called. If you want to use a color value before WindowInitializeSystem() is called, you can use the uppercase equivalent of the above variables, with Page 322 The C Window Library Page 322 a trailing underscore character attached to the name. For example BLACK_ would be used instead of black, WHITE_ would be used instead of white, etc. For monochrome systems, the only colors that are available are black, white, and intense white. An attribute of blue creates an underline attribute, and light blue creates an intense underlined attribute. Any other combination on a monochrome system is undefined. GET_BGROUND_COLOR(c) - Returns the background color of the video attribute c. GET_FGROUND_COLOR(c) - Returns the foreground color of the video attribute c. GET_OFFSET(x) - Returns the offset of a pointer x. The pointer can be either near or far. GET_SEGMENT(x) - Returns the segment address of a pointer x. The pointer can be either near or far. MAKE_FAR_POINTER(a,b) - Creates a far pointer made up of segment address a, and offset address b. SCREEN_OFFSET(r,c,a) - Returns the screen offset of the address of a character located at row r and column c of the video page a. The screen segment is defined in the macro SCREEN_SEGMENT. both r and c should be >= 1. Example: char far *p; p = MAKE_FAR_POINTER(SCREEN_SEGMENT,SCREEN_OFFSET(1,1,0)); The above example has created a far pointer p that points to the screen buffer memory at row 1, column 1, on video page 0. SCREEN_OFFSET_ATTR(r,c,a) - Returns the screen offset of the address of a attribute located at row r and column c of the video page a. The screen segment is defined in the macro SCREEN_SEGMENT. both r and c should be >= 1. SCREEN_SEGMENT - Returns the screen segment of video page 0. This macro is a pseudonym for the variable scrnseg_. SCREEN_WRITE_METHOD - Returns 1 if writing directly to the screen, 0 if using the BIOS. You can also use this macro to assign the particular writing method. This macro Page 323 The C Window Library Page 323 controls the way The C Window Library will do screen updates. The default is 1 (write directly to screen). Example: #include "vidsys.h" int a,b; a = SCREEN_WRITE_METHOD; SCREEN_WRITE_METHOD = 1; This macro is a pseudonym for the variable scrnwrt_flag which is a member of the SYS_FLAGS structure video_system_flags. VIDEO_PAGESIZE - Returns the size (in bytes) of a video page. You can also assign values to VIDEO_PAGESIZE, but the best thing to do is to leave it alone unless you are familiar with the video system you are using. This macro is a pseudonym for the variable pagesize_. Example: #include "vidsys.h" int psize; psize = VIDEO_PAGESIZE; /* Return the current video page size */ The following macros are used to identify the monitor type and video card being used in the system. Note : These macros are pseudonyms for members in the SYS_FLAGS structure called video_system_flags. CGA_ACTIVE - Returns 1 if Color Graphics Adapter is active, 0 otherwise. EGA_ACTIVE - Returns 1 if EGA is active, 0 otherwise. EGA_COLOR_ATTACHED - Returns 1 if monitor hooked up to EGA is a high resolution color monitor, 0 otherwise. EGA_COLOR_ON - Returns 1 if EGA is in color mode, 0 otherwise. EGA_INSTALLED - Returns 1 if EGA is installed, 0 otherwise. HERCULES_ACTIVE - Returns 1 if Hercules adapter is active, 0 otherwise. MCGA_ACTIVE - Returns 1 if the MCGA is the active video card. Page 324 The C Window Library Page 324 MCGA_COLOR_ON - Returns 1 if MCGA is in color mode, 0 otherwise. MCGA_INSTALLED - Returns 1 if MCGA is installed (IBM PS/2 Model 30), 0 otherwise. MDA_ACTIVE - Returns 1 if MDA (Monochrome) adapter is active, 0 otherwise. MONO_MODE_ON - Returns 1 if Monochrome mode is on regardless of the adapter, 0 otherwise. VGA_ACTIVE - Returns 1 if VGA is active adapter, 0 otherwise. VGA_COLOR_ATTACHED - Returns 1 if monitor hooked up to VGA is analog color, 0 otherwise. VGA_COLOR_ON - Returns 1 if VGA is in color mode, 0 otherwise. VGA_INSTALLED - Returns 1 if VGA Adapter is installed, 0 otherwise. You should always check the ..._ACTIVE constants before checking for other aspects of the video system. For example, make sure that VGA_ACTIVE returns 1 before checking any other VGA_... macro. If VGA_ACTIVE is 1, then all VGA_... macros are valid. The same thing goes for EGA. MONO_MODE_ON is the only macro that can be tested regardless of the video adapter. The following are macros defined in version 1.0 of The C Window Library, which are still supported: CGA_MODE_ON - Same as CGA_ACTIVE. EGA_MODE_ON - Same as EGA_ACTIVE. VGA_MODE_ON - Same as VGA_ACTIVE. MCGA_MODE_ON - Same as MCGA_ACTIVE. EGA_MONO_ON - Returns 1 if EGA is in mono mode. VGA_MONO_ON - Returns 1 if VGA is in mono mode. MCGA_MONO_ON - Returns 1 if MCGA is in mono mode. You should not assign values to the above pseudo-constants unless you are completely familiar with The C Window Library's internal functions. LINEMODE25 - Returns 1 if screen displays 25 lines, 0 otherwise. LINEMODE43 - Returns 1 if screen displays 43 lines (EGA and VGA), 0 otherwise. LINEMODE50 - Returns 1 if screen displays 50 lines (VGA), 0 otherwise. Page 325 The C Window Library Page 325 BOX MACROS ---------- The list of defined box drawing macros is as follows: DOUBLEBOX SINGLEBOX MIXEDBOX1 MIXEDBOX2 HATCHBOX1 HATCHBOX2 HATCHBOX3 SOLIDBOX1 SOLIDBOX2 BLANKBOX DOTTEDLINE Each one of these macros are 8 character strings that can be used in functions that call for a string of box drawing characters. Page 326 The C Window Library Page 326 EXPLOSION MACROS ---------------- The list of explosion constants is as follows: NOEFFECT EXPLODE CONTRACT BRICKS MIDDLEROWOUT TOPBOTTOMIN TOPDOWN BOTTOMUP MIDDLECOLOUT LEFTRIGHTIN LEFTTORIGHT RIGHTTOLEFT Page 327 The C Window Library Page 327 KEYBOARD MACROS --------------- The following macros are used to get characters from the keyboard. They are prototyped in the file key.h. ENHANCED_KEYBOARD() - Returns 1 if there is an enhanced keyboard attached, 0 otherwise. FLUSH_KEYBOARD() - Flushes the keyboard buffer. GET_KEY() - Returns what key was pressed either as a character, or as a scan code if a non-ascii key is pressed. A list of scan codes are found in the file keycodes.h. GET_ENHANCED_KEY() - Same as GET_KEY() except that keys on the enhanced keyboards are distinguishable. For instance, the key on the keypad will return a different scan code than the Home key on the separate cursor movement pad. GET_SHIFT_STATE() - Returns the shift state of the keyboard. The shift state tells whether the Alt, Ctrl or Shift key was pressed, or if the Num Lock, Scroll Lock, or Caps Lock keys are on or off. The shift state is updated after each call to GET_KEY() or GET_ENHANCED_KEY(). Use a bitwise AND (&) when testing for these keys. The #defined constants that are used to test for the various keys is found in keycodes.h. Example: #include "key.h" #include "keycodes.h" #include <stdio.h> main() { int CurrentShift; GET_KEY(); /* both ALT and CTRL must be pressed */ CurrentShift = (GET_SHIFT_STATE() & ALT) && (GET_SHIFT_STATE() & CTRL); printf("The Ctrl and Alt key was %s pressed", CurrentShift?"":"not"); } Page 328 The C Window Library Page 328 ISKEYREADY() - Returns 1 if there is a key ready in the keyboard buffer, 0 otherwise. Keyboard Idle function ---------------------- When calling the GET_KEY() or GET_ENHANCED_KEY() macros, you can call a function while the program is waiting for a key to be pressed. The global variable key_idle_func is a function pointer that points to this function. Here is the prototype: void (*key_idle_func)(void) There are no arguments and no return value to this function. You must initialize this function pointer after you have called WindowInitializeSystem(). If not, the function you assigned will not be executed. Here is an example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) void count_numbers(void); int num = 0; main() { WindowInitializeSystem(); key_idle_func = count_numbers; ClearScreen(NORM); GET_KEY(); MoveCursor(2,1,0); VideoPrintf("You stopped the count at %d",num); } void count_numbers() { num++; MoveCursor(1,1,0); VideoPrintf("%d",num); delay(1000); } The program above keeps a counter going in the upper left hand corner of the screen until a key is pressed. If you want to unassign the key_idle_func function pointer, do the following: key_idle_func = VOIDNULLFN; This function can perform just about anything. One major use would be to update an on-screen clock while the keyboard is not being used. Page 329 The C Window Library Page 329 Keyboard Intercept function --------------------------- Before GET_KEY() and GET_ENHANCED_KEY() return a value, you can intercept the pending return value, examine it, and change the value to whatever you wish. This is good if you want to reassign keys easily. The function pointer to assign is key_intercept_func. Here is the prototype: unsigned (*key_intercept_func)(int which, unsigned keyval) The first argument is an integer that denotes whether a mouse button was pressed, or a key from the keyboard was pressed. If a keyboard key was pressed, the value of which is equal to KEYPRESSED, otherwise it is MOUSEPRESSED. If you do not have a mouse, or the mouse is not activated, this value will always be KEYPRESSED. More information on the mouse in the USING THE MOUSE section in the manual. The return value will be the new key value that GET_KEY() and GET_ENHANCED_KEY() will return. It is advisable to use the key codes described in "keycodes.h" if you are returning a non-ascii key. Here is an example: #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(black,white) unsigned switch_to_quotes(int,unsigned); unsigned oldchar; main() { int ch; WindowInitializeSystem(); key_intercept_func = switch_to_quotes; ClearScreen(NORM); ch = GET_KEY(); MoveCursor(1,1,0); VideoPrintf( "The old key was %c. The new code is %c",oldchar,ch); } unsigned switch_to_quotes(int which, unsigned keyval) { if (which == KEYPRESSED) { oldchar = keyval; return (unsigned)'"'; /* return a double quote */ } } Page 330 The C Window Library Page 330 The program above intercepts the return value of GET_KEY() and assigns the double quote character. The character is then printed out on the screen along with the character that was assigned. If you want to unassign the key_intercept_func function pointer, do the following: key_intercept_func = NULLFN; Checking for mouse button presses --------------------------------- The GET_MPRESS_KEY() and GET_MPRESS_ENHANCED_KEY() macros work the same as the GET_KEY() and GET_ENHANCED_KEY() macros, which are described below and used in some previous examples, except that GET_MPRESS_KEY() and GET_MPRESS_ENHANCED_KEY() also test to see if one or more mouse buttons has been pressed. When GET_MPRESS_KEY() or GET_MPRESS_ENHANCED_KEY() is called, the program is suspended until a key on the keyboard is pressed, or one or more mouse buttons has been pressed. The difference between these two macros is that GET_MPRESS_ENHANCED_KEY() recognizes keys on an enhanced (101 key) keyboard. Here is a prototype for both of these macros: unsigned int GET_MPRESS_KEY(int *which) unsigned int GET_MPRESS_ENHANCED_KEY(int *which) The only argument is a pointer to an integer which will contain either MOUSEPRESSED if the mouse was pressed, or KEYBOARDPRESSED if a key on the keyboard was pressed. The kyboard_idle_func and keyboard_intercept_func function pointers are fully implemented when either of these macros are called. Both of these macros return either the key that was struck, or the mouse button(s) that was(were) pressed. The values for these mouse buttons are as follows: MOUSELEFT_PRESS - Left button was pressed. MOUSERIGHT_PRESS - Right button was pressed. MOUSEMIDDLE_PRESS - Middle button was pressed. MOUSELEFTRIGHT_PRESS - Left and Right was pressed simultaneously. Page 331 The C Window Library Page 331 MOUSEMIDDLERIGHT_PRESS - Middle and Right buttons were pressed simultaneously. MOUSEMIDDLELEFT_PRESS - Middle and Left buttons pressed simultaneously. MOUSEMIDDLERIGHTLEFT_PRESS - Middle, right, and left buttons pressed simultaneously. If a keyboard key is hit, the return values are the same as for GET_KEY() or GET_ENHANCED_KEY(). Example: #include "cwlmouse.h" #include "window.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) void print_nums(); main() { int w,b; unsigned ch; WindowInitializeSystem(); ClearScreen(NORM); MouseInitializeSystem(MOUSE_FULL_INSTALL,&b,10,10); key_idle_func = print_nums; ch = GET_MPRESS_KEY(&w); VideoPrintf("\nThe %s was pressed. Value is %d", (w==MOUSEPRESSED?"Mouse":"Keyboard"),ch); MouseRestoreSystem(); } void print_nums() { static int count = 0; MoveCursor(1,1,0); VideoPrintf("%d",count++); } Page 332 The C Window Library Page 332 CURSOR MACROS ------------- The following macros are used for cursor manipulation. CREATE_CURSOR_SHAPE(startline, endline) - Forms an integer quantity representing a cursor with a starting scan line of scanline, and an ending scan line of endline. THIN - constant for a thin (underline) cursor. BLOCK - constant for a block (fat) cursor. INVISIBLE - constant for a hidden cursor. Page 333 The C Window Library Page 333 IMPORTANT GLOBAL VARIABLES -------------------------- There are global variables that you should be aware of in The C Window Library. Most of these variables can be changed, while others should be left alone. You must call WindowInitializeSystem() before modifying any of these variables. When describing the global variable, the following scheme is used: Variable variable name Defined in XXXXXX.h (file where variable is declared) Initialized in function call (function where variable gets its initial value) Purpose Description of variable's purpose. Default Value default value for variable. Modify Info Tells if variable should be modified. These variables are described in alphabetical order. Variable int active_video_page Defined in vidsys.h Initialized in WindowInitializeSystem() Purpose Current active video page. Modify Info Should be modified only by calling the SetActiveVideoPage() function. Page 334 The C Window Library Page 334 Variable int barmenu_button_press Defined in cwlmouse.h Initialized in MouseInitializeSystem() Purpose Holds the current button mouse button to press to move the highlight bar on bar menus. Default Value MOUSELEFT_PRESS. Modify Info Can be modified at any time. Variable int caldelay_ Defined vidsys.h Initialized in WindowInitializeSystem() Purpose This is a calibration count for the delay() function. Modify Info Should only be modified if the delay() function is giving inaccurate delay times. If the delay is too long, then caldelay_ should be decreased. If it is too short, then caldelay_ should be increased. Variable int check_existence_flag Defined in window.h Initialized in WindowInitializeSystem() Purpose Informs The C Window Library to check for window, virtual window, and for non-open window errors. If this variable is 1, the library routines will check for these conditions. If 0, these conditions are not checked. Default Value 1. Modify Info Can be modified at any time, but is recommended that this flag be left on for development work. Make sure that your application program is stable if you plan to turn off checking. Page 335 The C Window Library Page 335 Variable int chksnow_ Defined vidsys.h Initialized in WindowInitializeSystem() Purpose This variable controls whether the display should be checked for snow when writing directly to the screen. A value of 1 will check for snow, while a value of 0 will turn off snow checking. Default Value 0 (no snow checking). Modify Info Can be modified at any time. Variable int crt_status_port Defined vidsys.h Initialized in WindowInitializeSystem() Purpose This variable holds the value of the CRT status port. This port is used to test when it is safe to read or write characters to the screen without producing snow. Modify Info Should not be modified. Variable int default_cursor_mode Defined key.h Initialized in WindowInitializeSystem() Purpose Holds the mode that the WindowGet...() functions will operate in when called. The modes are either OVERSTRIKEMODE or INSERTMODE. Default Value OVERSTRIKEMODE. Modify Info Can be modified at any time. Example: default_cursor_mode = INSERTMODE; Page 336 The C Window Library Page 336 Variable int default_cursor_type[2] Defined key.h Initialized in WindowInitializeSystem() Purpose Holds the cursor shapes for OVERSTRIKEMODE and INSERTMODE input modes. Default Value default_cursor_type[OVERSTRIKEMODE] is set to a block cursor. default_cursor_type[INSERTMODE] is set to an underline cursor. Modify Info Can be modified at any time. Example: default_cursor_type[INSERTMODE] = CREATE_CURSOR_SHAPE(5,7); Variable int default_screen_attr Defined in vidsys.h Initialized in WindowInitializeSystem() Purpose Default video attribute used when any Video...() functions are called to write to the screen. Default Value 7 (black background, white foreground). Modify Info Can be modified at any time. Variable int enhanced_keyboard Defined in key.h Initialized in WindowInitializeSystem() Purpose Tells if an enhanced keyboard is attached. If enhanced_keyboard is 1, an enhanced keyboard is active, otherwise if 0, the keyboard is not an enhanced keyboard. Modify Info Can be modified safely. Page 337 The C Window Library Page 337 Variable int explosion_speed[12] Defined in window.h Initialized in WindowInitializeSystem() Purpose This array holds the number of milliseconds of delay for each of the special effects supported in The C Window Library. Default Value 10 (10 ms.), except for explosion_speed[BRICKS], which is 1 ms. Modify Info Can be modified safely at anytime. The way you would modify the values is to use the special effects constants. For example: explosion_speed[CONTRACT] = 5; The above example changes the explosion delay for the CONTRACT special effect to 5 ms. Variable int flush_keyboard_flag. Defined in key.h Initialized in WindowInitializeSystem(). Purpose Tells if the keyboard buffer should be flushed whenever the GET_KEY() or GET_ENHANCED_KEY() macros are called. A value of 1 means the buffer will be flushed. Default Value 0 (no flush). Modify Info Can be modified at any time. Page 338 The C Window Library Page 338 Variable VIDEO_CONFIG initial_video_startup Defined in vidsys.h Initialized in WindowInitializeSystem() Purpose Structure that holds the video configuration when WindowInitializeSystem() is called. Modify info Should not be modified if the initial video startup is desired when exiting an application. Variable char input_mask_char Defined in window.h Initialized in WindowInitializeSystem() Purpose Holds the mask character that is used for input routines. The character defined in input_mask_char is used in input masks to specify an input position in the edit field. Refer to the functions WindowGet..() functions for more information concerning character masks. Default Value '_' (0x5F). Modify Info Can be modified safely at any time, except when in the middle of a user defined function that was called by The C Window Library's input routines. Variable void (*key_idle_func)(void) Defined in key.h Initialized in WindowInitializeSystem() Purpose pointer that points to a function that is performed whenever the GET_KEY() and GET_ENHANCED_KEY() macros do not have a key ready to be processed. Modify Info Can be modified at any time. Page 339 The C Window Library Page 339 Variable unsigned (*key_intercept_func)(int which, unsigned keyval) Defined in key.h Initialized in WindowInitializeSystem() Purpose pointer that points to a function which traps any keystrokes that the GET_KEY() and GET_ENHANCED_KEY() macros will return. Modify Info Can be modified at any time. Variable int max_video_pages Defined in vidsys.h Initialized in WindowInitializeSystem() Purpose Total number of video pages detected by The C Window Library. Modify Info Should not be modified unless a modification to the screen_page_offset array was done. Variable int max_window_rank Defined in window.h Initialized in WindowInitializeSystem() Purpose Holds the rank value of the bottom-most (i.e. the window that will have all other windows covering it). Modify Info Do not modify. Page 340 The C Window Library Page 340 Variable int min_window_rank Defined in window.h Initialized in WindowInitializeSystem() Purpose Holds the rank value of the top-most visible window. Modify Info Do not modify. Variable int (*num_chars_entered_func)(char *string, int minchars) Defined in key.h Arguments string - string that was entered. minchars - minimum number of characters expected. Initialized in WindowInitializeSystem() Purpose Pointer to user-defined function that will be executed when the input manager detects that there were not enough characters entered. Default Value NULLFN. Variable int num_transparent_shadows[16] Defined in window.h Initialized in WindowInitializeSystem() Purpose Array of the number of transparent shadows that are currently displayed for each display page. Default Value 0 for each array element. Modify Info Do not modify. Page 341 The C Window Library Page 341 Variable WPOINTER orig_screen[16] Defined in window.h Initialized in WindowSaveInitial() Purpose Array of windows created when WindowSaveInitial() is called. The original screen for video page 0 is orig_screen[0], page 1 is orig_screen[1], etc. Modify Info You can use any window function on the original screen, except for ones that resize, move, hide, display, or close. If you write strings to the original screen, you will permanently destroy the contents of the original screen at the positions that have been modified. Example: WindowWriteString(orig_screen[0],"123",1,1); The above example writes "123" to the upper left hand corner of the original screen of video page 0. Variable int pagesize_ Defined in window.h Initialized in WindowInitializeSystem() Purpose Holds the size of a display page in bytes. Modify Info Should not be modified unless The C Window Library did not detect the correct video page size. Page 342 The C Window Library Page 342 Variable int popmenu_button_press Defined in cwlmouse.h Initialized in MouseInitializeSystem() Purpose Holds the current button mouse button to press to move the highlight bar on popup menus. Default Value MOUSELEFT_PRESS. Modify Info Can be modified at any time. Variable int (*reg_exp_error_func)(char *string, int nomatch) Defined in key.h Arguments string - string that was entered. nomatch - position of the first non-matching character. Initialized in WindowInitializeSystem() Purpose Pointer to user-defined function that will be executed when the input manager detects that there are illegal characters in the string when it is compared to the regular expression. This function is only called when it is not equal to NULLFN, and the CHECKREGEXP option is on. Default Value NULLFN. Modify info Can be modified at any time. Return Values Must return DONT_PROCESS or ACCEPT_INPUT. Variable unsigned char *screen_image[16] Defined in window.h Initialized in WindowInitializeSystem() Purpose Used for internal window management. Each Page 343 The C Window Library Page 343 pointer in the screen_image array points to an image of the current window organization of the screen. For example screen_image[0] is a pointer to the current window "layout" for video page 0. Modify Info DO NOT modify this. This array is VERY important when window updates are done. Variable unsigned char far *screen_page_offset[16] Defined in window.h Initialized in WindowInitializeSystem() Purpose Array of starting addresses of each video page. Modify Info You can modify if The C Window Library fails to detect video pages that your video card may have. Invalid video pages will set screen_page_offset[page] to a far NULL pointer, where page is the invalid video page. If there is a failure to detect video pages that your card may have, you can use the MAKE_FAR_POINTER macro to initialize. Example: screen_page_offset[page] = MAKE_FAR_POINTER(0xB000,0x2000); where page is the page to initialize. You should have the documentation of the video card on hand so that you are sure of the starting address of the video page. You must also adjust the global variable max_video_pages to reflect the new number of pages, and the pagesize_ variable to reflect the size of each video page. Page 344 The C Window Library Page 344 Variable int (*undef_akey_func)(char *string, unsigned key, int pos, int *newpos) Defined in key.h Arguments string - string currently entered. key - key that was hit. pos - position where cursor is in the input string. Purpose Pointer to a function that is executed when a key that is not defined in an input routines regular expression is pressed. Default Value NULLFN. Modify Info Can be modified at any time. Return Values Refer to the manual for more information. Variable int (*undef_fkey_func)(char *string, unsigned key, int pos, int *newpos) Defined in key.h Arguments string - string currently entered. key - key that was hit. pos - position where cursor is in the input string. Purpose Pointer to a function that is executed when a key that is not defined in an input routines regular expression is pressed. Purpose Pointer to a function that is executed when a key that is not defined in the window_edit_key array is pressed. Default Value NULLFN. Modify Info Can be modified at any time. Return Values Refer to to the main documentation for more information. Page 345 The C Window Library Page 345 Variable VWPOINTER virtual_window_ptrs[256] Defined in window.h Purpose Array of all initialized virtual window pointers. Modify Info Do not modify. Variable int visible_video_page Defined in vidsys.h Initialized in WindowInitializeSystem() Purpose Current visible video page. Modify Info Should be modified only by calling the SetVisibleVideoPage() function. Variable unsigned window_edit_key[12] Defined in window.h Initialized in WindowInitializeSystem() Purpose Array of edit key definitions. This array is used in the window input routines. Modify Info You can modify values in the array, provided that there are no duplicate definitions, and there is a definition for a key that terminates user input. Refer to the GETTING INPUT FROM WINDOWS section. Page 346 The C Window Library Page 346 Variable int window_error_code Defined in window.h Initialized in WindowInitializeSystem() Purpose Holds the last error that occurred as an integer. You should always check the value of window_error_code to determine what has happened if a function fails. All of the window and virtual window functions return an error status when things go wrong. However, only selected functions from the Video... family of functions set window_error_code. The value in window_error_code corresponds to the values found in the file werror.h. window_error_code does not reset itself if there are no errors. Default Value 0. Modify Info Safe to modify, but will always reset itself to an error condition if a function fails. Variable WPOINTER window_ptrs[256]; Defined in window.h Purpose Array of all initialized windows. Modify Info DO NOT modify. Variable WPOINTER window_rank[257]; Defined in window.h Purpose Array of all visible windows in rank order. Modify Info DO NOT modify. Page 347 The C Window Library Page 347